add browser test for translation

Author: mlwilkerson

.github/workflows/browser-tests.yml

@@ -108,6 +108,9 @@ jobs:
       - name: Run Pro Kit Tests
         run: cd browser-testing && npm run test:ci:browser-pro-kit
 
+      - name: Run Admin i18n Tests
+        run: cd browser-testing && npm run test:ci:browser-i18n
+
       - name: Debug on failure
         if: failure()
         run: |

browser-testing/README.md

@@ -74,6 +74,38 @@ and the Pro Kit tests like this:
 npm run test:ci:browser-pro-kit
 ```
 
+# Admin i18n Test (PR #304)
+
+`tests-using-mock-fa-api/i18n/adminTranslations.spec.js` is regression coverage
+for the admin JavaScript internationalization fix (PR #304): it verifies, in the
+browser, that the admin bundle's script translations load and are applied.
+
+Because this bug only manifests in the browser (the PHP hook ordering looked
+fine in isolation), it belongs here rather than in the PHPUnit suite.
+
+It runs as its own project (`i18n-chrome`) with a dedicated setup/teardown so it
+doesn't disturb the other cells, whose specs match UI text in **English**:
+
+- `setup/i18n.js` forces the locale to `de_DE` (via a direct `wp_options` write,
+  so no language pack download is needed) and installs a fixture JS translation
+  file (`support/admin-translations.de_DE.json`) into the WordPress container
+  under the exact name WordPress derives from the admin bundle's path.
+- `setup/i18nCleanup.js` (wired as the `setup-i18n` project's `teardown`) reverts
+  the locale and removes the fixture file.
+
+The fixture strings are intentionally prefixed with `TEST-DE —` so the browser
+assertions are unambiguous; they are test markers, not real German copy.
+
+Run it the way CI does:
+
+```bash
+npm run test:ci:browser-i18n
+```
+
+The setup installs the fixture file into the running WordPress container via
+`docker`. The container name defaults to `wordpress-ci` when `CI=true` and the
+local dev container otherwise; override with `WP_CONTAINER` if needed.
+
 # Console Output
 
 The JavaScript console output from the browser is silenced by default to avoid showing in the terminal.

browser-testing/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "scripts": {
     "test:ci:browser-pro-kit": "CI=true npm run test:browser-mocked-fa-api-pro-kit-all-browsers",
+    "test:ci:browser-i18n": "CI=true npx playwright test --project=i18n-chrome",
     "test:ci:browser-non-kit": "CI=true npm run test:browser-mocked-fa-api-legacy-cdn-all-browsers",
     "test:local:browser-pro-kit": "npm run test:browser-real-fa-api-pro-kit-all-browsers",
     "test:local:browser-non-kit": "npm run test:browser-real-fa-api-legacy-cdn-all-browsers",

browser-testing/playwright.config.js

@@ -32,6 +32,15 @@ const testConfigs = [
     name: 'mock-fa-api-legacy-cdn',
     testMatch: 'tests-using-mock-fa-api/using-legacy-cdn/*.spec.js',
     dependencies: ['reset']
+  },
+  {
+    // Admin JS translations (PR #304). Runs in a forced de_DE locale with a
+    // fixture translation file; setup-i18n establishes that and its teardown
+    // reverts it, so the English-text expectations of the other cells are
+    // unaffected. Not FA-API dependent.
+    name: 'i18n',
+    testMatch: 'tests-using-mock-fa-api/i18n/*.spec.js',
+    dependencies: ['setup-i18n']
   }
 ]
 
@@ -81,6 +90,24 @@ export default defineConfig({
       },
       dependencies: ['wp-login', 'reset']
     },
+    {
+      name: 'setup-i18n',
+      testDir,
+      testMatch: 'setup/i18n.js',
+      use: {
+        storageState: authFile
+      },
+      dependencies: ['wp-login', 'reset'],
+      teardown: 'teardown-i18n'
+    },
+    {
+      name: 'teardown-i18n',
+      testDir,
+      testMatch: 'setup/i18nCleanup.js',
+      use: {
+        storageState: authFile
+      }
+    },
     ...browserProjects
   ]
 })

browser-testing/setup/i18n.js

@@ -0,0 +1,46 @@
+import { test as setup } from '@wordpress/e2e-test-utils-playwright'
+import { execFileSync } from 'child_process'
+import path from 'path'
+import '../support/env.js'
+import {
+  LOCALE,
+  LANG_PLUGINS_DIR,
+  translationFileName,
+  wpContainer,
+  dbConnection
+} from '../support/i18nHelpers.js'
+
+// Establishes the preconditions for the admin JS-translation tests:
+//   1. force the site locale to de_DE, and
+//   2. install a fixture JS translation file for the admin bundle.
+//
+// Both are reverted by setup/i18nCleanup.js (wired as this project's teardown),
+// so the rest of the suite — whose specs match UI text in English — is
+// unaffected. This is a plain admin-page test and does not touch the Font
+// Awesome API.
+setup('set up admin i18n fixture', async () => {
+  // 1. Force the locale via a direct DB write. Going through the WPLANG option's
+  //    sanitize (as wp-cli / the Settings screen would) rejects a locale whose
+  //    language pack isn't installed; writing the row directly avoids needing a
+  //    language-pack download, keeping this hermetic.
+  const connection = await dbConnection()
+  await connection.execute(
+    'INSERT INTO `wp_options` (`option_name`, `option_value`, `autoload`) VALUES (?, ?, "yes") ' +
+      'ON DUPLICATE KEY UPDATE `option_value` = VALUES(`option_value`)',
+    ['WPLANG', LOCALE]
+  )
+  await connection.end()
+
+  // 2. Install the JS translation file under the exact name WordPress derives
+  //    from the admin bundle's path (see support/i18nHelpers.js). WordPress only
+  //    prints the setLocaleData bridge when such a file exists for the locale,
+  //    so this file is what makes the fix observable in the browser.
+  const container = wpContainer()
+  const fixture = path.resolve(__dirname, `../support/admin-translations.${LOCALE}.json`)
+  execFileSync('docker', ['exec', '-u', 'root', container, 'mkdir', '-p', LANG_PLUGINS_DIR])
+  execFileSync('docker', [
+    'cp',
+    fixture,
+    `${container}:${LANG_PLUGINS_DIR}/${translationFileName()}`
+  ])
+})

browser-testing/setup/i18nCleanup.js

@@ -0,0 +1,40 @@
+import { test as teardown } from '@wordpress/e2e-test-utils-playwright'
+import { execFileSync } from 'child_process'
+import '../support/env.js'
+import {
+  LANG_PLUGINS_DIR,
+  translationFileName,
+  wpContainer,
+  dbConnection
+} from '../support/i18nHelpers.js'
+
+// Reverts everything setup/i18n.js established, so the WordPress instance is left
+// with its default (English) locale and no fixture translation file. Wired as
+// the teardown of the `setup-i18n` project, so it runs after the i18n specs
+// finish. Each step is best-effort — teardown must not fail the run.
+teardown('tear down admin i18n fixture', async () => {
+  try {
+    const connection = await dbConnection()
+    await connection.execute(
+      'UPDATE `wp_options` SET `option_value` = "" WHERE `option_name` = "WPLANG"'
+    )
+    await connection.end()
+  } catch (e) {
+    console.warn(`i18n teardown: reverting WPLANG failed: ${e.message}`)
+  }
+
+  try {
+    const container = wpContainer()
+    execFileSync('docker', [
+      'exec',
+      '-u',
+      'root',
+      container,
+      'rm',
+      '-f',
+      `${LANG_PLUGINS_DIR}/${translationFileName()}`
+    ])
+  } catch (e) {
+    console.warn(`i18n teardown: removing translation file failed: ${e.message}`)
+  }
+})

browser-testing/support/admin-translations.de_DE.json

@@ -0,0 +1,18 @@
+{
+  "translation-revision-date": "2026-07-28 00:00:00+0000",
+  "generator": "font-awesome e2e fixture",
+  "domain": "messages",
+  "locale_data": {
+    "messages": {
+      "": {
+        "domain": "messages",
+        "lang": "de_DE",
+        "plural-forms": "nplurals=2; plural=(n != 1);"
+      },
+      "How are you using Font Awesome?": [ "TEST-DE — Wie verwendest du Font Awesome?" ],
+      "Use A Kit": [ "TEST-DE — Kit verwenden" ],
+      "Use CDN": [ "TEST-DE — CDN verwenden" ],
+      "Save Changes": [ "TEST-DE — Änderungen speichern" ]
+    }
+  }
+}

browser-testing/support/i18nHelpers.js

@@ -0,0 +1,49 @@
+import crypto from 'crypto'
+import mysql from 'mysql2/promise'
+
+// The locale we force the admin UI into for the translation tests.
+export const LOCALE = 'de_DE'
+
+export const TEXT_DOMAIN = 'font-awesome'
+
+// The script handle the plugin registers for its admin bundle
+// (FontAwesome::ADMIN_RESOURCE_HANDLE = 'font-awesome-official' . '-admin').
+export const ADMIN_HANDLE = 'font-awesome-official-admin'
+
+// Path of the admin bundle relative to the plugin root. The plugin registers it
+// from get_webpack_asset_url_base() . 'index.js' (= admin/build/index.js), and
+// WordPress hashes exactly this string to name the script's JSON translation
+// file: `<text-domain>-<locale>-<md5(relative-path)>.json`. See WordPress core
+// load_script_textdomain(). If the build output path changes, update this.
+export const RELATIVE_JS_PATH = 'admin/build/index.js'
+
+export const LANG_PLUGINS_DIR = '/var/www/html/wp-content/languages/plugins'
+
+/** The exact filename WordPress looks for when loading the admin bundle's translations. */
+export function translationFileName() {
+  const hash = crypto.createHash('md5').update(RELATIVE_JS_PATH).digest('hex')
+  return `${TEXT_DOMAIN}-${LOCALE}-${hash}.json`
+}
+
+/**
+ * Name of the running WordPress container to install the translation file into.
+ * Defaults to the CI container when CI=true, otherwise the local dev container.
+ * Override with WP_CONTAINER.
+ */
+export function wpContainer() {
+  return (
+    process.env.WP_CONTAINER ||
+    (process.env.CI === 'true' ? 'wordpress-ci' : 'com.fontawesome.wordpress-latest-dev')
+  )
+}
+
+/** Open a connection to the WordPress DB using the same env the rest of the suite uses. */
+export function dbConnection() {
+  return mysql.createConnection({
+    host: 'localhost',
+    user: process.env.WORDPRESS_DB_USER,
+    password: process.env.WORDPRESS_DB_PASSWORD,
+    database: process.env.WORDPRESS_DB_NAME,
+    port: process.env.WORDPRESS_DB_PORT
+  })
+}

browser-testing/tests-using-mock-fa-api/i18n/adminTranslations.spec.js

@@ -0,0 +1,49 @@
+import { test, expect } from '../../fixtures.js'
+import { ADMIN_HANDLE } from '../../support/i18nHelpers.js'
+
+// Regression coverage for PR #304.
+//
+// The bug: FontAwesome::maybe_enqueue_admin_assets() called
+// wp_set_script_translations() for the admin bundle BEFORE the script was
+// registered/enqueued, so WordPress never attached the textdomain, never printed
+// the setLocaleData bridge, and the React admin UI never received its
+// translations. The fix moved the call to run right after
+// enqueue_admin_js_assets().
+//
+// setup/i18n.js forces the locale to de_DE and installs a fixture translation
+// file, so with the fix in place these assertions pass; if the bug regresses the
+// bridge disappears and the strings stay in English, failing the test.
+test.describe('admin JS translations (PR #304)', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/wp-admin/admin.php?page=font-awesome')
+  })
+
+  test('prints the script-translations bridge for the admin bundle', async ({ page }) => {
+    // The admin bundle must be on the page, otherwise the rest is meaningless.
+    await expect(page.locator(`#${ADMIN_HANDLE}-js`)).toHaveCount(1)
+
+    // The heart of the fix: WordPress only prints this inline setLocaleData
+    // script when wp_set_script_translations() ran AFTER registration. It's a
+    // <script> element (no rendered text), so read its textContent directly.
+    const bridge = page.locator(`#${ADMIN_HANDLE}-js-translations`)
+    await expect(bridge).toHaveCount(1)
+    const bridgeSource = await bridge.evaluate((el) => el.textContent)
+    expect(bridgeSource).toContain('wp.i18n.setLocaleData')
+    expect(bridgeSource).toContain('font-awesome')
+  })
+
+  test('renders translated strings in the admin UI', async ({ page }) => {
+    await expect(
+      page.getByRole('heading', { name: 'TEST-DE — Wie verwendest du Font Awesome?' })
+    ).toBeVisible()
+    await expect(page.getByText('TEST-DE — Kit verwenden')).toBeVisible()
+    await expect(page.getByText('TEST-DE — CDN verwenden')).toBeVisible()
+  })
+
+  test('resolves the plugin textdomain through the wp.i18n runtime', async ({ page }) => {
+    const translated = await page.evaluate(() =>
+      window.wp.i18n.__('How are you using Font Awesome?', 'font-awesome')
+    )
+    expect(translated).toBe('TEST-DE — Wie verwendest du Font Awesome?')
+  })
+})