ckeditor5 1.26.2 → 1.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e46c611bc11950481442cb335ae063943043937c9792b6eeedd731e030cdf1c
-  data.tar.gz: d16b561470173168c325457a00f5e83d5ca8689b0644f0d96533c05b7075193f
+  metadata.gz: 93b0f87e014924cf2ba04dc4d8ce96afef84152c4c8fc7bdebf5a736db864b95
+  data.tar.gz: 02b97648d5c94907741382795721e5944ecc0752c3b2792cfe0c7455c482f81f
 SHA512:
-  metadata.gz: 6769430ee90f270077c474bf1999e7d5fc4d2ec5c62918063e6503c39956e63a9f0bfb948de3dd376bc2bcb7212fc505a61e94cf04e46a1c2e85867d8e037e9a
-  data.tar.gz: 93071afc776e615781cc9ff845b631bc823653f229ee9dbba22ccc2f9e9b2c5b9813c4cfaf6d672dfc9764a8db6d205631cf992b2d94a16fe8aba9df230681ad
+  metadata.gz: 992f3a903d5bd123e91b572f0d0154c42044f90768264fe07a5c61d343431921ed3a45515f8f74ad48a68a0870876e9f73184cdc14266f4c0e43a4f393306a93
+  data.tar.gz: 64a1063477787141603fd850b6de704223c15b8dd6dbedcd713ea4a5ae69fb1ebf630ba1eaef9fc245a95272f4b32b40618065e04e0c69d72b8536677ef107bd

data/README.md

@@ -149,7 +149,9 @@ For extending CKEditor's functionality, refer to the [plugins directory](https:/
       - [`simple_upload_adapter(url)` method](#simple_upload_adapterurl-method)
       - [`special_characters(&block)` method](#special_charactersblock-method)
       - [`wproofreader(version: nil, cdn: nil, **config)` method](#wproofreaderversion-nil-cdn-nil-config-method)
+      - [`custom_translations(lang_code = nil, translations = {})` method](#custom_translationslang_code--nil-translations---method)
     - [Controller / View helpers 📦](#controller--view-helpers-)
+      - [`ckeditor5_translation_ref(key)` method](#ckeditor5_translation_refkey-method)
       - [`ckeditor5_element_ref(selector)` method](#ckeditor5_element_refselector-method)
       - [`ckeditor5_preset(name = nil, &block)` method](#ckeditor5_presetname--nil-block-method)
   - [Including CKEditor 5 assets 📦](#including-ckeditor-5-assets-)
@@ -1197,8 +1199,71 @@ For more info about the WProofreader plugin, check the [official documentation](
 
 </details>
 
+#### `custom_translations(lang_code = nil, translations = {})` method
+
+<details>
+  <summary>Define custom translations for CKEditor components and UI</summary>
+
+<br />
+
+Allows setting custom translations for editor components, UI elements, and headings. The translations are applied globally since they override the global translation object.
+
+> [!NOTE]
+> This helper allows overriding builtin translations of the editor, but translations are overridden globally, as the CKEditor 5 uses a single translation object for all instances of the editor. It's recommended to use the `ckeditor5_translation_ref` helper to reference the translations in the configuration.
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails.configure do
+  # ... other configuration
+
+  custom_translations :en, {
+    'Heading 1': 'Your custom translation value'
+  }
+
+  configure :heading, {
+    options: [
+      { model: 'heading1', title: ckeditor5_translation_ref('Heading 1') },
+      # ...
+    ]
+  }
+end
+```
+
+</details>
+
 ### Controller / View helpers 📦
 
+#### `ckeditor5_translation_ref(key)` method
+
+<details>
+  <summary>Defines a reference to a CKEditor 5 translation</summary>
+
+<br />
+
+Allows you to reference CKEditor 5 translations in the configuration. It's particularly useful when you want to use custom translations in the editor configuration.
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails.configure do
+  # ... other configuration
+
+  custom_translations :en, {
+    'Heading 1': 'Your custom translation value'
+  }
+
+  configure :heading, {
+    options: [
+      { model: 'heading1', title: ckeditor5_translation_ref('Heading 1') },
+      # ...
+    ]
+  }
+end
+```
+
+</details>
+
 #### `ckeditor5_element_ref(selector)` method
 
 <details>

data/lib/ckeditor5/rails/editor/helpers/config_helpers.rb

@@ -17,6 +17,20 @@ module CKEditor5::Rails::Editor::Helpers
       { '$element': selector }
     end
 
+    # Creates a reference to a translation key that will be used by CKEditor.
+    # This helper creates a special object that CKEditor recognizes as a translation reference.
+    #
+    # @param key [String] The translation key to reference
+    # @return [Hash] A hash with the translation reference in CKEditor's format
+    #
+    # @example Referencing a translation in plugin configuration
+    #   configure :toolbar, {
+    #     placeholder: ckeditor5_translation_ref("editor.placeholder")
+    #   }
+    def ckeditor5_translation_ref(key)
+      { '$translation': key }
+    end
+
     # Creates or retrieves a preset configuration for CKEditor.
     # When called with a name, finds and returns an existing preset.
     # When called with a block, creates a new preset with the given configuration.

data/lib/ckeditor5/rails/engine.rb

@@ -78,7 +78,7 @@ module CKEditor5::Rails
                :type, :menubar, :plugins, :plugin, :inline_plugin,
                :toolbar, :block_toolbar, :balloon_toolbar,
                :language, :ckbox, :configure, :automatic_upgrades, :simple_upload_adapter,
-               :editable_height, :wproofreader, to: :default_preset
+               :editable_height, :wproofreader, :custom_translations, to: :default_preset
 
       def initialize(configuration)
         @configuration = configuration

data/lib/ckeditor5/rails/plugins/custom_translations_loader.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative '../editor/props_inline_plugin'
+
+module CKEditor5::Rails::Plugins
+  class CustomTranslationsLoader < CKEditor5::Rails::Editor::PropsInlinePlugin
+    def initialize(translations) # rubocop:disable Metrics/MethodLength
+      code = <<~JS.freeze
+        const { Plugin } = await import('ckeditor5');
+
+        function resolveTranslationReferences(uiLanguage, config, visited = new WeakSet()) {
+          if (!config || typeof config !== 'object') {
+            return config;
+          }
+
+          if (visited.has(config)) {
+            return config;
+          }
+
+          visited.add(config);
+
+          if (Array.isArray(config)) {
+            config.forEach((item, index) => {
+              config[index] = resolveTranslationReferences(uiLanguage, item, visited);
+            });
+
+            return config;
+          }
+
+          for (const key of Object.getOwnPropertyNames(config)) {
+            const value = config[key];
+
+            if (value && typeof value === 'object') {
+              if (value.$translation) {
+                const translationKey = value.$translation;
+                const translations = window.CKEDITOR_TRANSLATIONS?.[uiLanguage];
+
+                if (!translations?.dictionary[translationKey]) {
+                  console.warn(`Translation not found for key: ${translationKey}`);
+                }
+
+                config[key] = translations?.dictionary[translationKey] || translationKey;
+              } else {
+                resolveTranslationReferences(uiLanguage, value, visited);
+              }
+            }
+          }
+
+          return config;
+        }
+
+        return class CustomTranslationsLoader extends Plugin {
+          static CUSTOM_TRANSLATIONS = Object.create( #{translations.to_json} );
+
+          static get pluginName() {
+            return 'CustomTranslationsLoader';
+          }
+
+          constructor( editor ) {
+            super( editor );
+
+            const { locale, config } = this.editor;
+
+            this.#extendPack();
+            resolveTranslationReferences(locale.uiLanguage, config._config)
+          }
+
+          #extendPack() {
+            const { uiLanguage } = this.editor.locale;
+            const translations = this.#translations;
+
+            if (!window.CKEDITOR_TRANSLATIONS) {
+              window.CKEDITOR_TRANSLATIONS = {};
+            }
+
+            if (!window.CKEDITOR_TRANSLATIONS[uiLanguage]) {
+              window.CKEDITOR_TRANSLATIONS[uiLanguage] = { dictionary: {} };
+            }
+
+            Object.entries(translations).forEach(([key, value]) => {
+              window.CKEDITOR_TRANSLATIONS[uiLanguage].dictionary[key] = value;
+            });
+          }
+
+          get #translations() {
+            const { uiLanguage } = this.editor.locale;
+
+            return CustomTranslationsLoader.CUSTOM_TRANSLATIONS[uiLanguage];
+          }
+        }
+      JS
+
+      super(:CustomTranslationsLoader, code)
+      compress!
+    end
+  end
+end

data/lib/ckeditor5/rails/plugins.rb

@@ -9,6 +9,7 @@ end
 require_relative 'plugins/simple_upload_adapter'
 require_relative 'plugins/wproofreader'
 require_relative 'plugins/special_characters_bootstrap'
+require_relative 'plugins/custom_translations_loader'
 
 # Plugin patches and fixes
 require_relative 'plugins/patches/fix_color_picker_race_condition'

data/lib/ckeditor5/rails/presets/preset_builder.rb

@@ -6,7 +6,7 @@ require_relative 'special_characters_builder'
 
 module CKEditor5::Rails
   module Presets
-    class PresetBuilder
+    class PresetBuilder # rubocop:disable Metrics/ClassLength
       include Editor::Helpers::Config
       include Concerns::ConfigurationMethods
       include Concerns::PluginMethods
@@ -27,6 +27,7 @@ module CKEditor5::Rails
         @ckbox = nil
         @editable_height = nil
         @automatic_upgrades = false
+        @custom_translations = {}
         @config = {
           plugins: [],
           toolbar: []
@@ -35,6 +36,12 @@ module CKEditor5::Rails
         instance_eval(&block) if block_given?
       end
 
+      def deconstruct_keys(keys)
+        keys.index_with do |key|
+          public_send(key)
+        end
+      end
+
       # @example Copy preset and modify it
       #   original = PresetBuilder.new
       #   copied = original.initialize_copy(original)
@@ -43,6 +50,7 @@ module CKEditor5::Rails
 
         @translations = source.translations.dup
         @ckbox = source.ckbox.dup if source.ckbox
+        @custom_translations = source.custom_translations.deep_dup
         @config = {
           plugins: source.config[:plugins].map(&:dup),
           toolbar: deep_copy_toolbar(source.config[:toolbar])
@@ -63,12 +71,6 @@ module CKEditor5::Rails
         license_key == 'GPL'
       end
 
-      def deconstruct_keys(keys)
-        keys.index_with do |key|
-          public_send(key)
-        end
-      end
-
       # Create a new preset by overriding current configuration
       # @example Override existing preset
       #   preset.override do
@@ -199,7 +201,7 @@ module CKEditor5::Rails
       # Apply integration patches for the current version
       # @return [void]
       def apply_integration_patches
-        patch_plugin Plugins::Patches::FixColorPickerRaceCondition.new
+        patch_plugin(Plugins::Patches::FixColorPickerRaceCondition.new)
       end
 
       # Enable or disable automatic version upgrades
@@ -333,6 +335,37 @@ module CKEditor5::Rails
         config[:language].present?
       end
 
+      # Configure custom translations for the editor
+      # @param lang_code [Symbol] Language code for translations (e.g. :en, :pl)
+      # @param translations [Hash] A hash containing translations in format { key => translation }
+      # @example Add multiple translations
+      #   custom_translations :en, {
+      #     'my.button': 'My Button'
+      #   }
+      #   custom_translations :pl, {
+      #     'my.button': 'Mój przycisk'
+      #   }
+      # @example Use translations in configuration with ckeditor5_translation_ref
+      #   custom_translations :en, {
+      #     'custom.heading': 'Custom Section'
+      #   }
+      #
+      #   configure :heading, {
+      #     options: [
+      #       { model: 'heading1', title: ckeditor5_translation_ref('custom.heading') }
+      #     ]
+      #   }
+      # @return [void]
+      def custom_translations(lang_code = nil, translations = {})
+        return @custom_translations if lang_code.blank?
+
+        @custom_translations[lang_code.to_sym] ||= {}
+        @custom_translations[lang_code.to_sym].merge!(translations)
+
+        plugins.remove(:CustomTranslationsLoader)
+        plugins.prepend(Plugins::CustomTranslationsLoader.new(@custom_translations))
+      end
+
       # Configure editor language
       # @param ui [Symbol, nil] UI language code
       # @param content [Symbol] Content language code

data/lib/ckeditor5/rails/version.rb

@@ -2,7 +2,7 @@
 
 module CKEditor5
   module Rails
-    VERSION = '1.26.2'
+    VERSION = '1.27.0'
 
     DEFAULT_CKEDITOR_VERSION = '44.2.0'
   end

data/spec/e2e/features/ajax_form_integration_spec.rb

@@ -8,7 +8,7 @@ RSpec.describe 'AJAX Form Integration', type: :feature, js: true do
     setup_form_tracking(page)
   end
 
-  shared_examples 'an ajax form with CKEditor' do |form_testid, editor_testid, submit_testid, response_id| # rubocop:disable Metrics/BlockLength
+  shared_examples 'an ajax form with CKEditor' do |form_testid, editor_testid, submit_testid, response_id|
     let(:form) { find("[data-testid='#{form_testid}']") }
     let(:editor) { find("[data-testid='#{editor_testid}']") }
     let(:editable) { editor.find('.ck-editor__editable') }

data/spec/e2e/features/editor_types_spec.rb

@@ -44,10 +44,10 @@ RSpec.describe 'CKEditor5 Types Integration', type: :feature, js: true do
     end
   end
 
-  shared_examples 'a multiroot editor that fires change events' do |path, editables| # rubocop:disable Metrics/BlockLength
+  shared_examples 'a multiroot editor that fires change events' do |path, editables|
     before { visit path }
 
-    it 'sends properly change events with proper payload for editables' do # rubocop:disable Metrics/BlockLength
+    it 'sends properly change events with proper payload for editables' do
       editors = editables.map do |name|
         find("[data-testid='#{name}-editable']")
       end
@@ -151,7 +151,7 @@ RSpec.describe 'CKEditor5 Types Integration', type: :feature, js: true do
       expect(page).to have_css('.ck-toolbar', count: 1)
     end
 
-    it 'handles dynamically added editables' do # rubocop:disable Metrics/BlockLength
+    it 'handles dynamically added editables' do
       # Set up event listener
       page.execute_script(<<~JS)
         window._newEditableEvents = [];

data/spec/e2e/features/form_integration_spec.rb

@@ -8,7 +8,7 @@ RSpec.describe 'Form Integration', type: :feature, js: true do
     setup_form_tracking(page)
   end
 
-  shared_examples 'a form with CKEditor' do |form_testid, editor_testid, submit_testid| # rubocop:disable Metrics/BlockLength
+  shared_examples 'a form with CKEditor' do |form_testid, editor_testid, submit_testid|
     let(:form) { find("[data-testid='#{form_testid}']") }
     let(:editor) { find("[data-testid='#{editor_testid}']") }
     let(:editable) { editor.find('.ck-editor__editable') }

data/spec/lib/ckeditor5/rails/presets/preset_builder_spec.rb

@@ -494,6 +494,61 @@ RSpec.describe CKEditor5::Rails::Presets::PresetBuilder do
     end
   end
 
+  describe '#custom_translations' do
+    it 'returns empty hash when called without arguments' do
+      expect(builder.custom_translations).to eq({})
+    end
+
+    it 'stores translations for a language' do
+      translations = { 'my.button': 'My Button' }
+      builder.custom_translations(:en, translations)
+      expect(builder.custom_translations).to eq({ en: translations })
+    end
+
+    it 'merges translations for the same language' do
+      builder.custom_translations(:en, { 'button.one': 'One' })
+      builder.custom_translations(:en, { 'button.two': 'Two' })
+
+      expect(builder.custom_translations[:en]).to eq({
+                                                       'button.one': 'One',
+                                                       'button.two': 'Two'
+                                                     })
+    end
+
+    it 'handles multiple languages' do
+      builder.custom_translations(:en, { 'button': 'Button' })
+      builder.custom_translations(:pl, { 'button': 'Przycisk' })
+
+      expect(builder.custom_translations).to eq({
+                                                  en: { button: 'Button' },
+                                                  pl: { button: 'Przycisk' }
+                                                })
+    end
+
+    it 'normalizes language codes to symbols' do
+      builder.custom_translations('EN', { 'button': 'Button' })
+      expect(builder.custom_translations.keys).to eq([:EN])
+    end
+
+    it 'adds and replaces CustomTranslationsLoader plugin' do
+      translations = { 'my.button': 'My Button' }
+
+      expect do
+        builder.custom_translations(:en, translations)
+      end.to change { builder.config[:plugins].count }.by(1)
+
+      plugin = builder.config[:plugins].first
+      expect(plugin).to be_a(CKEditor5::Rails::Plugins::CustomTranslationsLoader)
+
+      # Adding more translations should replace the plugin
+      expect do
+        builder.custom_translations(:pl, { 'my.button': 'Mój przycisk' })
+      end.not_to(change { builder.config[:plugins].count })
+
+      expect(builder.config[:plugins].first).to be_a(CKEditor5::Rails::Plugins::CustomTranslationsLoader)
+    end
+  end
+
   describe '#deep_copy_toolbar' do
     context 'with array toolbar' do
       it 'returns duplicated array' do
@@ -552,7 +607,7 @@ RSpec.describe CKEditor5::Rails::Presets::PresetBuilder do
       expect { builder.special_characters }.not_to raise_error
     end
 
-    it 'configures special characters with groups and items' do # rubocop:disable Metrics/BlockLength
+    it 'configures special characters with groups and items' do
       builder.special_characters do
         group 'Emoji', label: 'Emoticons' do
           item 'smiley', '😊'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ckeditor5
 version: !ruby/object:Gem::Version
-  version: 1.26.2
+  version: 1.27.0
 platform: ruby
 authors:
 - Mateusz Bagiński
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-13 00:00:00.000000000 Z
+date: 2025-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -90,6 +90,7 @@ files:
 - lib/ckeditor5/rails/hooks/importmap.rb
 - lib/ckeditor5/rails/hooks/simple_form.rb
 - lib/ckeditor5/rails/plugins.rb
+- lib/ckeditor5/rails/plugins/custom_translations_loader.rb
 - lib/ckeditor5/rails/plugins/patches/fix_color_picker_race_condition.rb
 - lib/ckeditor5/rails/plugins/simple_upload_adapter.rb
 - lib/ckeditor5/rails/plugins/special_characters_bootstrap.rb