feat: add translations: CLI commands and update runtime i18n integration (#205)

Adds two new CLI commands for managing translations, plus the runtime wiring to feed pulled translations into the app.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: brian-smith-tcril

docs/how_tos/migrate-frontend-app.md

@@ -269,6 +269,8 @@ packages/
 
 ### i18n ###
 src/i18n/transifex_input.json
+src/i18n/messages.ts
+src/i18n/messages/
 
 ### Editors ###
 .DS_Store
@@ -538,51 +540,45 @@ i18n
 
 Description fields are now required on all i18n messages in the repository.  This is because of a change to the ESLint config.
 
-Also, replace the contents of `src/i18n/index.js` with:
-
-```
-// Placeholder be overridden by `make pull_translations`
-export default {
-  ar: {},
-  'zh-hk': {},
-  'zh-cn': {},
-  uk: {},
-  'tr-tr': {},
-  th: {},
-  te: {},
-  ru: {},
-  'pt-pt': {},
-  'pt-br': {},
-  'it-it': {},
-  id: {},
-  hi: {},
-  he: {},
-  'fr-ca': {},
-  fa: {},
-  'es-es': {},
-  'es-419': {},
-  el: {},
-  'de-de': {},
-  da: {},
-  bo: {},
-};
+Translations are now pulled and prepared using the `openedx translations:pull` CLI command. Add an `atlasTranslations` field to your `package.json` so the command knows where to find your app's translations and which dependencies to resolve transitively:
+
+```json
+"atlasTranslations": {
+  "path": "translations/frontend-app-[YOUR_APP]/src/i18n/messages",
+  "dependencies": ["@openedx/frontend-base"]
+}
 ```
 
-Finally, edit the `Makefile` so that no strings are being pulled from `frontend-component-(header|footer)`, and rename `frontend-platform` to `frontend-base`.  Such as:
+Also add a `translations:pull` script to your `package.json`:
 
-```Makefile
-# Pulls translations using atlas.
-pull_translations:
-	mkdir src/i18n/messages
-	cd src/i18n/messages \
-	   && atlas pull $(ATLAS_OPTIONS) \
-	            translations/frontend-base/src/i18n/messages:frontend-base \
-	            translations/paragon/src/i18n/messages:paragon \
-	            translations/frontend-app-[YOUR_APP]/src/i18n/messages:frontend-app-[YOUR_APP]
+```json
+"scripts": {
+  "translations:pull": "openedx translations:pull"
+}
+```
+
+And update your `pull_translations` Makefile target to use it:
 
-	$(intl_imports) frontend-base paragon frontend-app-[YOUR_APP]
+```Makefile
+pull_translations: | requirements
+	npm run translations:pull
 ```
+
+Running `npm run translations:pull` will pull translations from `openedx-translations` and generate `src/i18n/messages.ts`.
+
+Add a `src/i18n/index.ts` file that re-exports the generated messages:
+
+```ts
+export { default } from './messages';
 ```
+
+Also add a `src/i18n/messages.d.ts` type declaration file so TypeScript knows the shape of the generated module even before `translations:pull` has been run:
+
+```ts
+import type { SiteMessages } from '@openedx/frontend-base';
+
+declare const messages: SiteMessages;
+export default messages;
 ```
 
 SVGR "ReactComponent" imports have been removed

frontend-base.d.ts

@@ -2,6 +2,10 @@ declare module 'site.config' {
   export default SiteConfig;
 }
 
+declare module 'site.i18n' {
+  export default SiteMessages;
+}
+
 declare module '*.svg' {
   const content: string;
   export default content;

package-lock.json

@@ -16,17 +16,23 @@
     "/dist"
   ],
   "bin": {
-    "intl-imports.js": "./dist/tools/cli/intl-imports.js",
-    "openedx": "./dist/tools/cli/openedx.js",
-    "transifex-utils.js": "./dist/tools/cli/transifex-utils.js"
+    "openedx": "./dist/tools/cli/openedx.js"
+  },
+  "atlasTranslations": {
+    "path": "translations/frontend-base/src/i18n/messages",
+    "dependencies": [
+      "@openedx/paragon"
+    ]
   },
   "scripts": {
     "build": "make build",
     "clean": "make clean",
     "dev": "npm run build && node ./dist/tools/cli/openedx.js dev:shell",
     "docs": "jsdoc -c jsdoc.json",
     "lint": "eslint .; npm run lint:tools; npm --prefix ./test-site run lint",
+    "lint:fix": "eslint . --fix; npm run lint:fix:tools",
     "lint:tools": "cd ./tools && eslint . && cd ..",
+    "lint:fix:tools": "cd ./tools && eslint . --fix && cd ..",
     "pack": "mkdir -p pack && npm pack --silent --pack-destination pack >/dev/null && mv \"$(ls -t pack/*.tgz | head -n 1)\" pack/openedx-frontend-base.tgz",
     "prepack": "npm run build",
     "test": "jest",
@@ -143,12 +149,12 @@
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
-    "@tsconfig/node20": "^20.1.5",
+    "@tsconfig/node24": "^24.0.4",
     "@types/compression": "^1.7.5",
     "@types/jest": "^29.5.14",
     "@types/lodash.camelcase": "^4.3.9",
     "@types/lodash.merge": "^4.6.9",
-    "@types/node": "^18.19.43",
+    "@types/node": "^24.12.0",
     "@types/react": "^18.3.20",
     "@types/react-dom": "^18.3.6",
     "axios-mock-adapter": "^1.22.0",
@@ -157,7 +163,7 @@
     "nodemon": "^3.1.4"
   },
   "peerDependencies": {
-    "@openedx/paragon": "^23.4.5",
+    "@openedx/paragon": "^23.20.0",
     "@tanstack/react-query": "^5.81.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",

package.json

@@ -97,7 +97,6 @@ export {
 } from 'react-intl';
 
 export {
-  addAppMessages,
   configureI18n,
   getLocale,
   getLocalizedLanguageName,

runtime/i18n/index.js

@@ -237,20 +237,6 @@ export function mergeMessages(newMessages = {}) {
   return messages;
 }
 
-/**
- * Adds all the messages found in the loaded apps.
- *
- * @memberof module:Internationalization
- */
-export function addAppMessages() {
-  const { apps } = getSiteConfig();
-  if (apps) {
-    apps.forEach((app) => {
-      mergeMessages(app.messages);
-    });
-  }
-}
-
 interface ConfigureI18nOptions {
   messages: LocalizedMessages[] | LocalizedMessages,
 }

runtime/i18n/lib.ts

@@ -1,6 +1,5 @@
 import { App } from '../../../types';
 import HomePage from './HomePage';
-import messages from './i18n';
 
 const app: App = {
   appId: 'org.openedx.frontend.app.dev.home',
@@ -12,7 +11,6 @@ const app: App = {
       role: 'org.openedx.frontend.role.devHome'
     }
   }],
-  messages,
 };
 
 export default app;

shell/dev/devHome/app.ts

@@ -10,16 +10,14 @@ import {
   subscribe
 } from '../runtime';
 import { addAppConfigs } from '../runtime/config';
-import { addAppMessages } from '../runtime/i18n';
-import messages from './i18n';
+import messages from 'site.i18n';
 import createRouter from './router/createRouter';
 
 subscribe(SITE_READY, async () => {
   const queryClient = new QueryClient();
   const router = createRouter();
 
   addAppConfigs();
-  addAppMessages();
 
   const root = createRoot(document.getElementById('root') as HTMLElement);
   root.render(