feat: Internationlization (#120)

* build: Add node-fetch dependency

Utilized for script requests.

* feat: Add locale configuration

* feat: Configure locale

* build: Add download translations script

* task: Add logger utility

Standardized logging within the code.

* refactor: Utilize logger utility

* feat: Match translations supported by Gutenberg Mobile

* fix: Repair translations data path

* fix: Start demo editor

The editor no longer implicitly starts.

* build: Add GUTERNBERG_EDITOR_REMOTE_URL environment value

Simplify configuration with examples.

* fix: Repair script logger import path

* task: Reduce translation download script noise

* feat: Control log levels for scripts

* fix: Use default value from dynamic import

* refactor: Rename API fetch utility

Consistently name utility files as objects.

* refactor: Rename exception parser utility

Consistently name utility files as objects.

* fix: Postpone importing `@wordpress` packages until after setting locale

Required to ensure imported files have the correct locale set.

* refactor: Translate strings within `gutenberg-kit` domain

Ensure all project-specific strings are translated.

* fix: Use existing Gutenberg "Block Settings" string

Two benefits:

1. Align with Gutenberg
2. Use the existing translation

* fix: Apply `@wordpress` package import postponement to remote editor

Required to ensure imported files have the correct locale set.

* refactor: Rename GBKit global await utility

Clarify the utility's purpose.

* fix: Repair localization operations order

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.

* task: Log additional values

* refactor: Separate concerns of loading assets and unregistering blocks

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

* refactor: Replace verbose log level with debug

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

* refactor: Replace redundant logger prefix with unique project prefix

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

* task: Capture build output

* build: Manually chunk editor utility

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.

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

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

* task: Capture build output

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

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

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

Limit scope of file responsibilities.

* refactor: `initializeEditor` provides default WP packages

Simplify initializing the local editor.

* build: Prevent unintentional preloading of `@wordpress` modules

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)

* task: Capture build output

* fix: Workaround circular dependency

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`.

* task: Capture build output

* refactor: Remove unused module

Usage was removed in a earlier commit.

* build: Cache translation strings

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

* refactor: Flatten translations directory

Avoid unnecessary nesting.

* refactor: Clarify translation script cache interaction

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

* build: Add clean scripts

Simplify resetting build caches.

* task: Capture build output

* refactor: Remove unused export

This is only used within the module.

* fix: Organize dynamic imports and chunks to avoid circular dependencies

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.

* refactor: Remove unnecessary dependency injection

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.

* task: Capture build output

Author: dcalhoun

.gitignore

@@ -193,3 +193,6 @@ local.properties
 # /ios/Sources/GutenbergKit/Gutenberg/assets
 # /ios/Sources/GutenbergKit/Gutenberg/index.html
 # /ios/Sources/GutenbergKit/Gutenberg/remote.html
+
+# Translation files
+src/translations/

Makefile

@@ -10,12 +10,18 @@ define XCODEBUILD_CMD
 endef
 
 npm-dependencies:
-	@if [ "$(SKIP_DEPS)" != "true" ]; then \
+	@if [ "$(SKIP_DEPS)" != "true" ] && [ "$(SKIP_DEPS)" != "1" ]; then \
 		echo "--- :npm: Installing NPM Dependencies"; \
 		npm ci; \
 	fi
 
-build: npm-dependencies
+prep-translations:
+	@if [ "$(SKIP_L10N)" != "true" ] && [ "$(SKIP_L10N)" != "1" ]; then \
+		echo "--- :npm: Preparing Translations"; \
+		npm run prep-translations -- --force; \
+	fi
+
+build: npm-dependencies prep-translations
 	echo "--- :node: Building Gutenberg"
 
 	npm run build

android/Gutenberg/src/main/java/org/wordpress/gutenberg/EditorConfiguration.kt

@@ -60,7 +60,8 @@ open class EditorConfiguration constructor(
     val namespaceExcludedPaths: Array<String>,
     val authHeader: String,
     val webViewGlobals: List<WebViewGlobal>,
-    val editorSettings: String?
+    val editorSettings: String?,
+    val locale: String?
 ) : Parcelable {
     companion object {
         @JvmStatic
@@ -82,6 +83,7 @@ open class EditorConfiguration constructor(
         private var authHeader: String = ""
         private var webViewGlobals: List<WebViewGlobal> = emptyList()
         private var editorSettings: String? = null
+        private var locale: String? = "en"
 
         fun setTitle(title: String) = apply { this.title = title }
         fun setContent(content: String) = apply { this.content = content }
@@ -97,6 +99,7 @@ open class EditorConfiguration constructor(
         fun setAuthHeader(authHeader: String) = apply { this.authHeader = authHeader }
         fun setWebViewGlobals(webViewGlobals: List<WebViewGlobal>) = apply { this.webViewGlobals = webViewGlobals }
         fun setEditorSettings(editorSettings: String?) = apply { this.editorSettings = editorSettings }
+        fun setLocale(locale: String?) = apply { this.locale = locale }
 
         fun build(): EditorConfiguration = EditorConfiguration(
             title = title,
@@ -112,7 +115,8 @@ open class EditorConfiguration constructor(
             namespaceExcludedPaths = namespaceExcludedPaths,
             authHeader = authHeader,
             webViewGlobals = webViewGlobals,
-            editorSettings = editorSettings
+            editorSettings = editorSettings,
+            locale = locale
         )
     }
 
@@ -136,6 +140,7 @@ open class EditorConfiguration constructor(
         if (authHeader != other.authHeader) return false
         if (webViewGlobals != other.webViewGlobals) return false
         if (editorSettings != other.editorSettings) return false
+        if (locale != other.locale) return false
 
         return true
     }
@@ -155,6 +160,7 @@ open class EditorConfiguration constructor(
         result = 31 * result + authHeader.hashCode()
         result = 31 * result + webViewGlobals.hashCode()
         result = 31 * result + (editorSettings?.hashCode() ?: 0)
+        result = 31 * result + (locale?.hashCode() ?: 0)
         return result
     }
 }

android/Gutenberg/src/main/java/org/wordpress/gutenberg/GutenbergView.kt

@@ -271,6 +271,7 @@ class GutenbergView : WebView {
                 "themeStyles": ${configuration.themeStyles},
                 "hideTitle": ${configuration.hideTitle},
                 "editorSettings": $editorSettings,
+                "locale": "${configuration.locale}",
                 ${if (configuration.postId != null) """
                 "post": {
                     "id": ${configuration.postId},

bin/prep-translations.js

@@ -0,0 +1,158 @@
+/**
+ * External dependencies
+ */
+import fs from 'fs';
+import path from 'path';
+import fetch from 'node-fetch';
+
+/**
+ * Internal dependencies
+ */
+import { info, error, debug } from '../src/utils/logger.js';
+
+const TRANSLATIONS_DIR = path.join( process.cwd(), 'src/translations' );
+const SUPPORTED_LOCALES = [
+	'ar', // Arabic
+	'bg', // Bulgarian
+	'bo', // Tibetan
+	'ca', // Catalan
+	'cs', // Czech
+	'cy', // Welsh
+	'da', // Danish
+	'de', // German
+	'en-au', // English (Australia)
+	'en-ca', // English (Canada)
+	'en-gb', // English (UK)
+	'en-nz', // English (New Zealand)
+	'en-za', // English (South Africa)
+	'el', // Greek
+	'es', // Spanish
+	'es-ar', // Spanish (Argentina)
+	'es-cl', // Spanish (Chile)
+	'es-cr', // Spanish (Costa Rica)
+	'fa', // Persian
+	'fr', // French
+	'gl', // Galician
+	'he', // Hebrew
+	'hr', // Croatian
+	'hu', // Hungarian
+	'id', // Indonesian
+	'is', // Icelandic
+	'it', // Italian
+	'ja', // Japanese
+	'ka', // Georgian
+	'ko', // Korean
+	'nb', // Norwegian (Bokmål)
+	'nl', // Dutch
+	'nl-be', // Dutch (Belgium)
+	'pl', // Polish
+	'pt', // Portuguese
+	'pt-br', // Portuguese (Brazil)
+	'ro', // Romainian
+	'ru', // Russian
+	'sk', // Slovak
+	'sq', // Albanian
+	'sr', // Serbian
+	'sv', // Swedish
+	'th', // Thai
+	'tr', // Turkish
+	'uk', // Ukrainian
+	'ur', // Urdu
+	'vi', // Vietnamese
+	'zh-cn', // Chinese (China)
+	'zh-tw', // Chinese (Taiwan)
+];
+
+/**
+ * Prepare translations for all supported locales.
+ *
+ * @param {boolean} force Whether to force download even if cache exists.
+ *
+ * @return {Promise<void>} A promise that resolves when translations are prepared.
+ */
+async function prepareTranslations( force = false ) {
+	if ( force ) {
+		info( 'Ignoring cache, downloading translations...' );
+	} else {
+		info( 'Verifying translations...' );
+	}
+
+	for ( const locale of SUPPORTED_LOCALES ) {
+		try {
+			await downloadTranslations( locale, force );
+		} catch ( err ) {
+			error( `✗ Failed to download translations for ${ locale }:`, err );
+		}
+	}
+
+	info( '✓ Translations ready!' );
+}
+
+/**
+ * Downloads translations for a specific locale from translate.wordpress.org.
+ *
+ * @param {string}  locale The locale to download translations for.
+ * @param {boolean} force  Whether to force download even if cache exists.
+ *
+ * @return {Promise<void>} A promise that resolves when translations are downloaded.
+ */
+async function downloadTranslations( locale, force = false ) {
+	if ( ! force && hasValidTranslations( locale ) ) {
+		debug( `Skipping download of cached translations for ${ locale }` );
+		return;
+	}
+	debug( `Downloading translations for ${ locale }...` );
+
+	const url = `https://translate.wordpress.org/projects/wp-plugins/gutenberg/dev/${ locale }/default/export-translations/?format=json`;
+	const response = await fetch( url );
+
+	if ( ! response.ok ) {
+		throw new Error( `Failed to download translations for ${ locale }` );
+	}
+
+	const translations = await response.json();
+	const outputPath = path.join( TRANSLATIONS_DIR, `${ locale }.json` );
+
+	// Ensure the translations directory exists
+	if ( ! fs.existsSync( TRANSLATIONS_DIR ) ) {
+		fs.mkdirSync( TRANSLATIONS_DIR, { recursive: true } );
+	}
+
+	// Write translations to file
+	fs.writeFileSync( outputPath, JSON.stringify( translations, null, 2 ) );
+	debug( `✓ Downloaded translations for ${ locale }` );
+}
+
+/**
+ * Checks if translations exist and are valid for a specific locale.
+ *
+ * @param {string} locale The locale to check.
+ *
+ * @return {boolean} Whether valid translations exist.
+ */
+function hasValidTranslations( locale ) {
+	const filePath = path.join( TRANSLATIONS_DIR, `${ locale }.json` );
+	if ( ! fs.existsSync( filePath ) ) {
+		return false;
+	}
+
+	try {
+		const content = fs.readFileSync( filePath, 'utf8' );
+		const translations = JSON.parse( content );
+		return translations && typeof translations === 'object';
+	} catch ( err ) {
+		return false;
+	}
+}
+
+/**
+ * Main entry point for the script.
+ * Parses command line arguments and downloads translations.
+ */
+const forceDownload =
+	process.argv.includes( '--force' ) || process.argv.includes( '-f' );
+
+prepareTranslations( forceDownload ).catch( ( err ) => {
+	error( 'Failed to prepare translations:', err );
+	process.exit( 1 );
+} );

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

@@ -56,6 +56,11 @@
             value = "http://localhost:5173/"
             isEnabled = "NO">
          </EnvironmentVariable>
+         <EnvironmentVariable
+            key = "GUTENBERG_EDITOR_REMOTE_URL"
+            value = "http://localhost:5174/remote.html"
+            isEnabled = "NO">
+         </EnvironmentVariable>
       </EnvironmentVariables>
    </LaunchAction>
    <ProfileAction

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()
         return viewController
     }