feat: Internationlization #120

dcalhoun · 2025-05-02T00:40:57Z

What?

Add internationalization (i18n) support.

Why?

Ref CMM-280. Close #110. I18n improves the editor usability.

How?

Download and utilize translation strings from translate.wordpress.org.

Testing Instructions

Tip

Use the prototype builds for testing:

Important

Not all languages are supported, only those supported by Gutenberg Mobile.
Strings from third-party plugins are not supported at this time.

1: Verify translations in the local editor

Change your device language/region.
Open the editor.
Verify various UI element utilize the expected translation strings.

2: Verify translations in the remote editor

Enable the Experimental block editor plugins (iOS) or gutenberg_kit_plugins (Android) debug flag.
Change your device language/region.
Open the editor.
Verify various UI element utilize the expected translation strings.

Accessibility Testing Instructions

N/A, no navigation changes.

Screenshots or screencast

N/A, no visual changes.

Utilized for script requests.

Standardized logging within the code.

The editor no longer implicitly starts.

Simplify configuration with examples.

Consistently name utility files as objects.

Required to ensure imported files have the correct locale set.

Ensure all project-specific strings are translated.

Two benefits: 1. Align with Gutenberg 2. Use the existing translation

Required to ensure imported files have the correct locale set.

Clarify the utility's purpose.

In order to set the locale before critical `@wordpress` packages load, we must load i18n packages separately from the rest of the `@wordpress` packages. Otherwise, the locale will not be set in time and/or we will encounter collisions from loading packages more than once.

These feel like two separate concerns. Separating them hopefully reduces complexity.

Two, distinct levels provided little-to-no value.

Prefixing with the log level duplicates browser log level styles. Prefixing the project name or acronym at least provides additional context.

It's unclear why this manual chunk configuration is required, but the editor fails to load without it. The dynamic import of the module never resolves.

There is no reason to attempt loading the default locale. There will never be a translation file.

Using static imports means the packages are loaded before the locale is set, leading to incorrect translation strings in various places.

If the editor fails early in the load process, these styles need to be present for presenting error message UI. Therefore, we hoist them to the entry file.

Limit scope of file responsibilities.

Simplify initializing the local editor.

The locale must be set before most `@wordpress` modules load, as they rely upon globals for retrieving translation strings. However, the manual chunks configuration seemingly led to preloading of all `@wordpress` modules even before they were dynamically imported. vitejs/vite#8617 (comment)

A circular dependency causes the dynamic import to never resolve. Using a Promise circumvents the issue, as it appears to function differently than top-level await. Ideally, we resolve the circular dependency. However, using Rollup's `manualChunks` configuration does not appear to be an option, as it results in preloading of `@wordpress` modules. The preloading results in untranslated strings as `@wordpress` modules load before the globals they rely upon for localization, which are set by `setLocaleData`.

Usage was removed in a earlier commit.

Allow for avoiding unnecessary network requests when translation strings are already present.

Avoid unnecessary nesting.

Communicate the cache is ignored when using the `force` flag.

Simplify resetting build caches.

This is only used within the module.

Because we load internationalization modules before the rest of the `@wordpress` modules, we must strategically chunk modules to avoid circular dependencies. Additionally, Vite injects its own helper utilities seem to create their own circular dependencies, at times. Lastly, the correct chunk configuration for the `index` entry is a bit complicated and allusive. Instead, we rely upon a `Promise` rather than `async`/`await`, as the latter will timeout when a circular dependency exists.

Because of the latest dynamic import strategy and Vite managing externalizing `@wordpress` modules for the remote editor, we no longer need to use DI for these functions. For the local editor, the imported modules will be bundled and imported. For the remote editor, the imported modules will be replaced with global `window.wp` references.

dcalhoun

Apologies for the files changed count; the bulk of them are build output for iOS, necessary until we finish #45.

dcalhoun · 2025-05-09T14:17:45Z

bin/prep-translations.js

+import { info, error, debug } from '../src/utils/logger.js';
+
+const TRANSLATIONS_DIR = path.join( process.cwd(), 'src/translations' );
+const SUPPORTED_LOCALES = [


These are the same translations supported by Gutenberg Mobile.

dcalhoun · 2025-05-09T14:18:19Z

ios/Demo-iOS/Gutenberg.xcodeproj/xcshareddata/xcschemes/Gutenberg.xcscheme

+         <EnvironmentVariable
+            key = "GUTENBERG_EDITOR_REMOTE_URL"
+            value = "http://localhost:5174/remote.html"
+            isEnabled = "NO">
+         </EnvironmentVariable>


Disabled by default. Added to simplify testing the remote editor.

dcalhoun · 2025-05-09T14:19:29Z

ios/Demo-iOS/Sources/EditorView.swift

@@ -77,6 +77,7 @@ private struct _EditorView: UIViewControllerRepresentable {
        if #available(iOS 16.4, *) {
            viewController.webView.isInspectable = true
        }
+        viewController.startEditorSetup()


Adding this required start call to the demo app was overlooked during #114.

dcalhoun · 2025-05-09T14:23:40Z

src/components/default-block-appender/index.jsx

@@ -33,7 +33,7 @@ export default function DefaultBlockAppender() {

 	return (
 		<button
-			aria-label={ __( 'Add paragraph block' ) }
+			aria-label={ __( 'Add paragraph block', 'gutenberg-kit' ) }


The addition of the gutenberg-kit domain properly groups the project-specific string.

dcalhoun · 2025-05-09T14:24:12Z

src/components/editor-toolbar/index.jsx

@@ -76,7 +76,7 @@ const EditorToolbar = ( { className } ) => {
 				{ isSelected && (
 					<ToolbarGroup>
 						<ToolbarButton
-							title={ __( 'Open Settings' ) }
+							title={ __( 'Block Settings' ) }


Changed to reuse the existing, translated Gutenberg project string.

dcalhoun · 2025-05-09T14:33:10Z

vite.config.js

-		rollupOptions: {
-			output: {
-				manualChunks: {
-					// Chunk to avoid circular dependency
-					bridge: [ 'src/utils/bridge.js' ],
-				},
-			},
-		},


Configuring manualChunks results in preloading of @wordpress modules—this appears to be a Vite feature. However, it disrupts internationalization (i18n) within the @wordpress modules. The @wordpress modules rely upon globals for retrieving locale strings. So, if the loading order is incorrect, certain strings are unavailable and missing.

Long term, we may be able to address this by expressly disabling preloading. For now, I opted to remove the manual chunk altogether.

The referenced circular dependency is address within the entry file by using a Promise rather than async/await.

dcalhoun · 2025-05-09T20:42:54Z

src/index.scss

The only change is wrapping all selectors with a .gutenberg-kit selector to increase specificity. The increased specificity is required as the styles are now loaded before styles from @wordpress modules, which impacts how CSS prioritizes style application.

dcalhoun · 2025-05-09T20:43:13Z

src/utils/blocks.js

Separated from src/utils/editor.js to limit responsibilities.

dcalhoun · 2025-05-09T20:43:28Z

src/utils/logger.js

Added to standardize logging within the project.

dcalhoun · 2025-05-09T20:43:46Z

src/utils/remote-editor.js

This existing code from relocated from src/remote.jsx to limit responsibilities of files and reuse editor initialization logic between src/index.jsx and src/remote.jsx.

dcalhoun · 2025-05-09T20:44:05Z

src/utils/editor.jsx

Existing logic abstracted to a new location for sharing editor initialization logic between src/index.jsx and src/remote.jsx.

kean

LGTM.
I tested one of the translations (Russian) and haven't noticed any issues in the implementation.

dcalhoun added 20 commits April 30, 2025 11:52

build: Add node-fetch dependency

95b456c

Utilized for script requests.

feat: Add locale configuration

e4c7b9a

feat: Configure locale

cbddc69

build: Add download translations script

38b30f1

task: Add logger utility

a42af38

Standardized logging within the code.

refactor: Utilize logger utility

fd4c654

feat: Match translations supported by Gutenberg Mobile

e128481

fix: Repair translations data path

da26c1b

fix: Start demo editor

6ab424e

The editor no longer implicitly starts.

build: Add GUTERNBERG_EDITOR_REMOTE_URL environment value

c47453d

Simplify configuration with examples.

fix: Repair script logger import path

edfd17f

task: Reduce translation download script noise

6b78bf8

feat: Control log levels for scripts

971e831

fix: Use default value from dynamic import

bf9614a

refactor: Rename API fetch utility

9f22787

Consistently name utility files as objects.

refactor: Rename exception parser utility

e3d5a25

Consistently name utility files as objects.

fix: Postpone importing @wordpress packages until after setting locale

5a48230

Required to ensure imported files have the correct locale set.

refactor: Translate strings within gutenberg-kit domain

3ee0c86

Ensure all project-specific strings are translated.

fix: Use existing Gutenberg "Block Settings" string

aa9bbf3

Two benefits: 1. Align with Gutenberg 2. Use the existing translation

fix: Apply @wordpress package import postponement to remote editor

25dd3a0

Required to ensure imported files have the correct locale set.

dcalhoun added the [Type] Enhancement A suggestion for improvement. label May 2, 2025

dcalhoun added 6 commits May 2, 2025 08:55

refactor: Rename GBKit global await utility

913bd9f

Clarify the utility's purpose.

task: Log additional values

d682d15

refactor: Separate concerns of loading assets and unregistering blocks

3f29a15

These feel like two separate concerns. Separating them hopefully reduces complexity.

refactor: Replace verbose log level with debug

935c64f

Two, distinct levels provided little-to-no value.

refactor: Replace redundant logger prefix with unique project prefix

948dc37

Prefixing with the log level duplicates browser log level styles. Prefixing the project name or acronym at least provides additional context.

dcalhoun force-pushed the feat/internationalization branch from 1d43f80 to 948dc37 Compare May 2, 2025 14:46

dcalhoun added 2 commits May 2, 2025 10:54

task: Capture build output

ce3e042

build: Manually chunk editor utility

df1ea42

It's unclear why this manual chunk configuration is required, but the editor fails to load without it. The dynamic import of the module never resolves.

dcalhoun added 20 commits May 2, 2025 17:10

fix: Avoid errors loading non-existent, default locale translations

30097d5

There is no reason to attempt loading the default locale. There will never be a translation file.

task: Capture build output

9c0bdc3

fix: Lazy load bundled @wordpress packages after locale is set

26bcf2a

Using static imports means the packages are loaded before the locale is set, leading to incorrect translation strings in various places.

fix: Ensure foundational styles are available for early error UI

be3786b

If the editor fails early in the load process, these styles need to be present for presenting error message UI. Therefore, we hoist them to the entry file.

refactor: Separate block utilities

f2682b8

Limit scope of file responsibilities.

refactor: initializeEditor provides default WP packages

930917b

Simplify initializing the local editor.

task: Capture build output

0bb5fe6

task: Capture build output

1b3e577

refactor: Remove unused module

a003792

Usage was removed in a earlier commit.

build: Cache translation strings

56ece8c

Allow for avoiding unnecessary network requests when translation strings are already present.

refactor: Flatten translations directory

9e9f53b

Avoid unnecessary nesting.

refactor: Clarify translation script cache interaction

6a0df4a

Communicate the cache is ignored when using the `force` flag.

build: Add clean scripts

e812448

Simplify resetting build caches.

task: Capture build output

48fd3e7

refactor: Remove unused export

c4e7789

This is only used within the module.

task: Capture build output

e83c5f9

dcalhoun commented May 9, 2025

View reviewed changes

dcalhoun marked this pull request as ready for review May 9, 2025 21:06

dcalhoun requested a review from kean May 9, 2025 21:07

This was referenced May 9, 2025

feat: GutenbergKit internationalization wordpress-mobile/WordPress-iOS#24515

Merged

feat: GutenbergKit internationalization wordpress-mobile/WordPress-Android#21854

Merged

kean approved these changes May 12, 2025

View reviewed changes

dcalhoun merged commit fdfe788 into trunk May 12, 2025
9 of 10 checks passed

dcalhoun deleted the feat/internationalization branch May 12, 2025 20:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Internationlization #120

feat: Internationlization #120

Uh oh!

dcalhoun commented May 2, 2025 •

edited

Loading

Uh oh!

dcalhoun left a comment

Uh oh!

dcalhoun May 9, 2025

Uh oh!

dcalhoun May 9, 2025

Uh oh!

dcalhoun May 9, 2025

Uh oh!

dcalhoun May 9, 2025

Uh oh!

dcalhoun May 9, 2025

Uh oh!

dcalhoun May 9, 2025

Uh oh!

dcalhoun May 9, 2025

Uh oh!

dcalhoun May 9, 2025

Uh oh!

dcalhoun May 9, 2025

Uh oh!

dcalhoun May 9, 2025

Uh oh!

dcalhoun May 9, 2025

Uh oh!

kean left a comment

Uh oh!

Uh oh!

Uh oh!

feat: Internationlization #120

feat: Internationlization #120

Uh oh!

Conversation

dcalhoun commented May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Accessibility Testing Instructions

Screenshots or screencast

Uh oh!

dcalhoun left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kean left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dcalhoun commented May 2, 2025 •

edited

Loading