i18n pipeline

[arbrandes]

Description

For now, this is a discovery: is the frontend-base i18n pipeline fully developed? We might be missing an atlas pull step in our publish pipeline not only for the apps, but for frontend-base itself.  Or maybe this should only happen in frontend-template-site.

Should we ship libraries with full translations?  It seems this would be a new thing: frontend-component-[header|footer] only extract i18n as part of the release workflow, leaving the atlas pull to the MFE.

See this Slack thread for some more context and preliminary findings.

[brian-smith-tcril]

Open questions on this one:

• We will have both legacy (MFE) and modern (frontend-base) versions of apps for a while, which version should the openedx-translations repo's extract_translation_source_files workflow use?
  • If master (the MFE version), how do we make sure our source strings are covered?
    • One possible way would be to add a "base only strings" file somewhere on master to cover it
  • If frontend-base, how do we handle strings that we don't need in the frontend-base version but we do in the MFE version?
  • If both, how do we not overwhelm translators with multiple copies of apps?
    • There's some tooling in transifex, but that could get messy.
    • It might also be possible to handle this in the extract workflow by running extract on both branches and then combining the source strings.

[arbrandes]

When we decided to go with two versions of MFEs, we already decided to put more work on the plate of developers - and IMHO, this includes translators. In other words, let's do both. If we want to lessen the load (which we do), we should speed up the demise of MFEs (which we want).

I don't know enough about Transifex to decide whether its tooling is good enough, but if we can solve this on the Atlas end (or, specifically, the workflow end) without losing anything that already sounds good enough for me.

[brian-smith-tcril]

Claude generated comment

Goal 1

Update the extract-translation-source-files workflow in openedx-translations to handle repos that exist on both a master (legacy MFE) branch and a frontend-base branch. During the transition period, both branches need to be extracted and their strings combined into a single transifex_input.json for Transifex.

Affected repos: frontend-app-authn, frontend-app-learner-dashboard

What's done

• .nvmrc fix (openedx-translations#66732) — openedx-translations workflow was hardcoding Node 16; switched all setup-node steps to use node-version-file: '.nvmrc' (Node 20). Landed on main.
• openedx/frontend-base#200 — Simplified i18n extraction in frontend-base to output flat {"key": "value"} JSON directly to src/i18n/transifex_input.json, matching the format used by all other frontend repos. Eliminates the need for a separate concat step. Merged 2026-03-25.
• Combine logic implemented — Initially written as inline jq, then switched to actions/github-script@v8 (Node 24) on recommendation for maintainability and readability. It:
  • Merges both flat KV transifex_input.json files via object spread ({ ...master, ...base }), with frontend-base winning on conflicts
  • Detects conflicts (same key, different value) by filtering Object.entries(master), building a conflicts object, and writing a formatted table to core.summary if any are found. The heading makes clear this is an expected consequence of dual-branch support, not a bug.

What's in progress

• dual-js-translations job (openedx-translations#66785, draft) — draft PR open, blocked on a new frontend-base version being published so the frontend-base branches of frontend-app-authn and frontend-app-learner-dashboard can be updated and the extract flow verified end-to-end.
• Publish new frontend-base version — PR feat: simplify i18n extraction to output flat KV directly #200 landed but a new npm package version hasn't been published yet.
• Update frontend-base branches of frontend-app-authn and frontend-app-learner-dashboard — blocked on the new frontend-base version being published.

Decisions & notes

• Combine logic is inline in the workflow (not a separate script) — expected to stay small.
• Conflict goals: include all strings from both branches (extras ok, missing strings not ok); frontend-base is source of truth for duplicate keys.
• Conflict notification uses core.summary (job summary tab, formatted markdown table) rather than core.warning (annotation). Chose summary because the annotation list on these runs is already very noisy — dominated by Node 20 deprecation warnings, one per job — so a warning would get buried. Summary is a dedicated, clean page.
  • Slack notification or CI checks in the MFE repos — more robust but out of scope for now

Follow-up (out of scope for this work)

• Update .nvmrc in openedx-translations from Node 20 to Node 24 (to match actions/github-script@v8)

Next steps

1. Branch off the dual-js-translations work into its own PR in openedx-translations done (#66785)
2. Publish new frontend-base version
3. Update the frontend-base branches of frontend-app-authn and frontend-app-learner-dashboard
4. Test the full workflow end-to-end and merge openedx-translations#66785

[brian-smith-tcril]

Digging into the pull side of this (claude generated):

Translation Pulling for frontend-base Sites — Design Summary

Problem

In the MFE/SPA model, each app has its own make pull_translations target that pulls translations for itself and shared libs. In the frontend-base model, apps are npm packages installed into a site (e.g., frontend-template-site). We need a site-level mechanism to pull all translations using atlas.

Design Constraints

• Site operators should not need to think about translations in site.config.tsx
• One command at the site level should cover all installed apps + shared libs
• Translations should be deduplicated (e.g., paragon pulled once, not per-app)
• Translation source path convention (translations/{package-name}/src/i18n/messages) is reliable but shouldn't be assumed

Package Configuration

Each translatable package declares an atlasTranslations block in its package.json:

// paragon/package.json
{
  "name": "@openedx/paragon",
  "atlasTranslations": {
    "path": "translations/paragon/src/i18n/messages"
  }
}

// frontend-base/package.json
{
  "name": "@openedx/frontend-base",
  "atlasTranslations": {
    "path": "translations/frontend-base/src/i18n/messages",
    "dependencies": ["@openedx/paragon"]
  }
}

// frontend-app-authn/package.json
{
  "name": "@openedx/frontend-app-authn",
  "atlasTranslations": {
    "path": "translations/frontend-app-authn/src/i18n/messages",
    "dependencies": ["@openedx/frontend-base"]
  }
}

• path: the FROM path for atlas (what to pull from the translations repo)
• dependencies: npm package names whose translations are also needed (targeted transitive resolution — only follows explicitly declared deps, never touches react/webpack/etc.)

Site-level config

The site explicitly lists which apps to pull translations for (no path — site translations are not part of the Open edX project and don't exist in the openedx-translations repo, so there's nothing for atlas to pull; site-local translations are managed separately in src/i18n/site-messages/):

// frontend-template-site/package.json
{
  "name": "@openedx/frontend-template-site",
  "atlasTranslations": {
    "dependencies": [
      "@openedx/frontend-app-authn",
      "@openedx/frontend-app-learner-dashboard"
    ]
  }
}

This is a tentative decision — the alternative (auto-scanning direct deps) avoids duplication but risks tricky-to-debug issues if a transitive dep ever needs translations.

CLI Commands

Two new openedx CLI commands:

openedx translations:pull

Fetches translations from atlas and prepares them for the build.

1. Read site's atlasTranslations.dependencies
2. Recursively resolve each package's atlasTranslations config (following dependencies)
3. Collect all unique path values, deduplicate
4. Build atlas FROM:TO mappings (using full package name with scope as TO)
5. Run atlas pull to get JSON files into src/i18n/messages/
6. Run translations:prepare automatically (controlled by --prepare flag, defaults to true; pass --no-prepare to skip)

openedx translations:prepare

Turns pulled JSON files into a JS/TS module the build can consume. Replaces the old intl-imports tool.

1. Scan src/i18n/messages/ for package directories containing JSON files
2. Generate per-package index files
3. Generate main src/i18n/index.ts

File Structure After Pull

src/i18n/
├── index.ts                    ← checked in, operator-controlled (re-exports messages.ts)
├── messages.ts                 ← generated by translations:prepare (gitignored, force-added placeholder)
├── site-messages/              ← operator's own translations, checked in
│   ├── ar.json
│   ├── fr.json
│   └── ...
└── messages/                   ← generated by translations:pull, gitignored
    └── @openedx/
        ├── frontend-app-authn/
        │   ├── index.ts        ← generated by translations:prepare
        │   ├── ar.json
        │   ├── fr.json
        │   └── ...
        ├── frontend-base/
        │   ├── index.ts
        │   ├── ar.json
        │   └── ...
        └── paragon/
            ├── index.ts
            ├── ar.json
            └── ...

Generated Module Shape

Per-package (src/i18n/messages/@openedx/frontend-app-authn/index.ts):

import ar from './ar.json';
import es_419 from './es_419.json';

export default {
  'ar': ar,
  'es-419': es_419,
};

Main generated file (src/i18n/messages.ts — generated by prepare, gitignored + force-added placeholder):

import authnMessages from './messages/@openedx/frontend-app-authn';
import paragonMessages from './messages/@openedx/paragon';
import frontendBaseMessages from './messages/@openedx/frontend-base';
import siteMessages from './site-messages';

export default [
  authnMessages,
  paragonMessages,
  frontendBaseMessages,
  siteMessages,  // last — wins the merge, enabling overrides
];

Entry point (src/i18n/index.ts — checked in, operator-controlled):

export { default } from './messages';

This indirection means:

• prepare never touches a file the operator might have customized
• Operators can edit index.ts for custom behavior while still importing prepared messages
• Default case just re-exports — works out of the box
• Without running prepare, the force-added placeholder (export default [];) ensures the app still works with just defaultMessage strings

The output is LocalizedMessages[] — an array of Record<string, Record<string, string>> objects (locale → message key → translated string). Per-package structure keeps things navigable; the runtime flattens everything via merge({}, ...array).

Runtime Integration

The site imports the generated module and passes it to initialize():

import siteMessages from './src/i18n';

initialize({
  messages: siteMessages,
});

This covers everything — app translations and library translations (paragon, frontend-base). The existing configureI18n / mergeMessages machinery handles the array merge. No runtime changes required.

Site-Local Translations

Site operators may have their own translatable strings (e.g., a custom homeApp). Rather than forking openedx-translations, the recommendation is to check site translations into src/i18n/site-messages/ in the site repo.

src/i18n/
├── index.ts              ← generated by translations:prepare
├── site-messages/        ← operator's own translations, checked in
│   ├── ar.json
│   ├── fr.json
│   └── ...
└── messages/             ← generated by translations:pull, gitignored
    └── @openedx/
        ├── frontend-app-authn/
        ├── frontend-base/
        └── paragon/

• messages/ is gitignored — generated from atlas, safe to blow away on each pull
• site-messages/ is checked in — operator-managed, never touched by translations:pull
• translations:prepare generates index.ts for both messages/ and site-messages/, with site-messages last in the array so they win the merge — enabling manual translation overrides without forking openedx-translations
• site-messages/index.ts is gitignored (generated by prepare), but the *.json files are tracked
• If site-messages/ doesn't exist or is empty, prepare skips it gracefully
• This directory structure should be added to frontend-template-site as part of this work

Gitignore for src/i18n/:

src/i18n/messages.ts
src/i18n/messages/
src/i18n/site-messages/index.ts

messages.ts is gitignored but force-added (git add -f) as an empty placeholder so it exists on fresh clone.

Bundle Size / Lazy Loading

Currently all translations are one chunk passed to initialize({ messages }). Ideally only the needed locale would be loaded. Webpack may chunk automatically depending on import pattern. Not a blocking concern — can revisit if bundle size becomes an issue.

What Gets Removed

• messages field from the App type
• addAppMessages() from the runtime
• The addAppMessages() call in shell/site.tsx
• Per-app src/i18n/index.js placeholder files
• intl-imports CLI tool (replaced by translations:prepare)

Standalone Dev

Apps like authn have their own site.config.dev.tsx and run openedx dev — they are a site in dev mode. openedx translations:pull works identically: read atlasTranslations from package.json, pull, prepare, feed into initialize(). No separate flow needed.

Key Design Decisions

Decision	Rationale
Config in package.json, not TypeScript	Pull runs before build — needs static reads, no TS execution. Custom package.json fields are an established JS ecosystem pattern (browserslist, babel, eslint, jest, stylelint). Config is small (~3 lines), not worth a separate file. atlas.yml is for atlas CLI config, not package metadata.
atlasTranslations as the key name	Ties clearly to atlas, avoids generic names
path + dependencies (targeted transitive)	Apps declare their own path + immediate deps; framework follows the chain, deduplicates
Full package name (with scope) as local dir	Explicit, avoids collisions, no deriving needed
Site explicitly lists deps (option B)	Unambiguous, avoids scanning pitfalls, low duplication cost
Per-package index files	Keeps generated code navigable with many apps
Remove app.messages / addAppMessages()	All translations come through site-level initialize({ messages })
translations:pull + translations:prepare as separate commands	Can regenerate without re-pulling, or pull without generating

Full conversation log

Conversation Log

Session: 2026-03-30

Goal

Design how frontend-template-site should pull translations for all installed apps using atlas.

Discussion

Problem statement (user): MFEs each have a pull_translations Makefile target, but those are designed around each MFE being an SPA. In the frontend-base world, apps are npm packages installed into a site (see frontend-template-site). The goal is to have a target in template-site that pulls all the translations needed by everything for the site using atlas.

Exploration: We reviewed the current state:

• MFE model: Each app has its own pull_translations that calls atlas pull for itself + shared libs (paragon, frontend-base/platform), then runs intl-imports to generate JS index files. Each app bundles its own translations.
• frontend-base model: Apps are npm dependencies. Each app's App object has a messages property. At runtime, addAppMessages() merges them all under a single IntlProvider.
• frontend-template-site: Currently has NO i18n/translation-pulling mechanism.

Where should translation wiring live? We considered two options:

1. Site config attaches translations to each app explicitly
2. Runtime/build handles it automatically — site pulls translations to a known location, frontend-base discovers and merges them

Key constraint (user): Site operators control their site config — they should NOT need to think about translations. Translation wiring should be invisible to operators. This rules out option 1.

What needs to be pulled? We identified two categories:

1. Shared libs (paragon, frontend-base) — always needed, site-level concern
2. Per-app translations — each app's own strings

In MFEs, each app redundantly pulls shared libs. In the site model, shared libs get pulled once (deduplicated).

How does the site know which apps need translations? Not every npm dependency is a translatable app (e.g., react). We need an opt-in signal. The App config registered in site config is already that signal — if it's in the apps array, it's an Open edX app.

Convention for translation source paths: The path translations/{package-name}/src/i18n/messages is reliable across apps. So if we know the package name, we can derive the atlas source automatically.

Current gap: The App config has appId (e.g., 'authn') but not the npm package name (e.g., @openedx/frontend-app-authn). We can't derive the atlas translation path from appId alone. Options discussed:

• Add a field to App config (package name or translation source path)
• Establish a convention mapping appId to package name
• Something else — still open

Looking at the site config for clues: We reviewed site.config.dev.tsx. Apps are imported from their npm packages:

import { authnApp } from '@openedx/frontend-app-authn';
import { learnerDashboardApp } from '@openedx/frontend-app-learner-dashboard';

The import path is the package name, but at build/pull time we're not executing this code so we can't extract it from imports directly.

Simpler angle — use package.json: The site's package.json already lists app packages as dependencies. A pull tool could:

1. Read package.json dependencies
2. Filter for packages matching @openedx/frontend-app-* (the opt-in signal)
3. Derive atlas paths: translations/{package-name-without-scope}/src/i18n/messages
4. Always also pull shared libs (paragon, frontend-base)

This would mean:

• No changes to the App type
• No changes to site config
• Signal is already in package.json — install an app, its translations get pulled automatically

Open question: Are there translatable apps that wouldn't match the @openedx/frontend-app-* pattern?

User: yes, and string matching is fragile. So we're back to needing an explicit signal from each app.

Best place for the signal: the App type. Apps declare their own translation source, framework handles the rest. Example:

const authnApp: App = {
  appId: 'authn',
  translationSource: 'frontend-app-authn',
  // ... routes, slots, messages
};

• Apps opt in by including the field
• Pull tool iterates installed apps, collects translationSource values, builds atlas pull command
• Shared libs (paragon, frontend-base) always included by framework
• Site operators don't touch any of this

Timing problem: The pull tool runs before build time, but translationSource lives in TypeScript code that needs to be executed/imported to read. Options:

1. A build-time script that imports the site config and extracts the sources (possible since it's TS)
2. Apps declare the source in package.json metadata (statically readable, no execution needed)
3. A separate static config file per app

Decision: static metadata over executing code. Atlas is a bash script; requiring Node/TS execution just to discover translation sources adds complexity and fragility. Static package.json metadata keeps it simple.

Proposed convention: Apps declare translation source in package.json:

{
  "name": "@openedx/frontend-app-authn",
  "openedx": {
    "translationSource": "frontend-app-authn"
  }
}

Pull script flow:

1. Read site's package.json to get dependency list
2. For each dependency, read node_modules/{package}/package.json
3. If it has openedx.translationSource, include it in the atlas pull
4. Always include shared libs (paragon, frontend-base)

All just JSON reads + shell — no build toolchain needed. Apps that aren't translatable simply don't include the field.

Refinement (user): apps should declare ALL their translation dependencies, not just their own. This matches how pull_translations works today — authn pulls paragon + frontend-platform + its own. The framework aggregates and deduplicates across all apps.

Using full paths for flexibility. Use the full atlas path (e.g., translations/paragon/src/i18n/messages) rather than just a package name. This handles cases where a dependency puts translations in a non-standard location.

Updated package.json convention:

{
  "name": "@openedx/frontend-app-authn",
  "openedx": {
    "translationSources": [
      "translations/paragon/src/i18n/messages",
      "translations/frontend-platform/src/i18n/messages",
      "translations/frontend-app-authn/src/i18n/messages"
    ]
  }
}

Pull script flow (updated):

1. Iterate all deps, collect every openedx.translationSources array
2. Deduplicate (e.g., paragon appears in both authn and learner-dashboard, pulled once)
3. Build one atlas pull command with all unique sources

Transitive resolution (user suggestion): Rather than each app listing all deps (paragon, frontend-base, its own), use transitive resolution mirroring how npm works:

• frontend-base declares in its package.json: translationSources: ["translations/frontend-base/src/i18n/messages", "translations/paragon/src/i18n/messages"]
• An app like authn only declares its own: translationSources: ["translations/frontend-app-authn/src/i18n/messages"]
• Pull script walks the dep tree: reads app sources, then reads frontend-base's sources (since it's a dep of authn), picking up paragon transitively
• If frontend-base ever adds a new translatable peer dep, all apps get it automatically

Clarification on "no defaults needed": User asked whether apps would need to explicitly define frontend-base. Answer: no — the transitive walk handles it automatically. Every app in this ecosystem depends on frontend-base as an npm dependency, so the pull script would:

1. See frontend-app-authn has translationSources → collect its own source
2. Walk into authn's deps, find @openedx/frontend-base has translationSources → collect frontend-base + paragon
3. The "defaults" emerge naturally from the dependency tree — no explicit config needed

The app author only declares their app's own translations. Frontend-base and paragon come along for free because they're already npm dependencies.

Problem with transitive walk (user): Walking the dep tree puts us back in the "how do we know which packages to look at" problem. We'd be reading potentially hundreds of package.json files (react, webpack, lodash, etc.) to find the few that matter. Even if we filter to only packages with openedx.translationSources, we still have to read them all to check.

Reconsidering the flat model: Each app explicitly lists everything it needs:

{
  "name": "@openedx/frontend-app-authn",
  "openedx": {
    "translationSources": [
      "translations/frontend-app-authn/src/i18n/messages",
      "translations/frontend-base/src/i18n/messages",
      "translations/paragon/src/i18n/messages"
    ]
  }
}

Pros: no tree walking, no ambiguity, matches existing pull_translations pattern, simple pull script (collect arrays, deduplicate, pull). Con: if frontend-base adds a translatable dep, each app needs updating — but how often does that happen?

Clarification on where this lives: This is in package.json, NOT in the TypeScript App config (app.ts). The App type and site config are purely runtime concerns. The pull script only reads package.json files — no TypeScript execution needed.

Hybrid approach (user proposal): translationsPath + translationsDeps. Each package declares two things:

1. translationsPath — its own translation source path in the atlas repo
2. translationsDeps — which other packages it needs translations from (by npm package name)

The pull script follows translationsDeps to read those packages' translationsPath, recursively but only through explicitly declared deps. This is targeted transitive resolution — never touches react/webpack/etc.

Example configs (updated to final naming):

// paragon/package.json
{
  "name": "@openedx/paragon",
  "atlasTranslations": {
    "path": "translations/paragon/src/i18n/messages"
  }
}

// frontend-base/package.json
{
  "name": "@openedx/frontend-base",
  "atlasTranslations": {
    "path": "translations/frontend-base/src/i18n/messages",
    "dependencies": ["@openedx/paragon"]
  }
}

// frontend-app-authn/package.json
{
  "name": "@openedx/frontend-app-authn",
  "atlasTranslations": {
    "path": "translations/frontend-app-authn/src/i18n/messages",
    "dependencies": ["@openedx/frontend-base"]
  }
}

Pull script resolution for authn:

1. Read authn → path + dependencies: ["@openedx/frontend-base"]
2. Read frontend-base → path + dependencies: ["@openedx/paragon"]
3. Read paragon → path, no further deps
4. Collected (deduplicated): authn + frontend-base + paragon

Benefits:

• Targeted transitive resolution — only follows explicitly declared deps
• Apps only declare their immediate translation deps (authn says "frontend-base", not "frontend-base + paragon")
• If frontend-base adds a new translatable dep, only frontend-base's package.json needs updating — all apps get it automatically
• Pull script is still simple: recursive JSON reads, then one atlas pull command

Examining the FROM:TO mapping. User shared the file structure after make pull_translations in authn (master). Atlas uses FROM:TO syntax where the TO becomes the local subdirectory name:

atlas pull translations/paragon/src/i18n/messages:paragon \
         translations/frontend-platform/src/i18n/messages:frontend-platform \
         translations/frontend-app-authn/src/i18n/messages:frontend-app-authn

Result:

src/i18n/messages/
├── frontend-app-authn/   ← TO alias
│   ├── ar.json, ...
├── frontend-platform/    ← TO alias
│   ├── ar.json, ...
└── paragon/              ← TO alias
    ├── ar.json, ...

Then intl-imports generates index.js files for each subdirectory.

The translationsPath (FROM) should only be used to tell atlas what to pull. User doesn't want to derive anything else (like the TO alias / local dir name) from the path — keep those concerns separate.

Deriving the TO alias: The local directory name could be derived from the npm package name (strip the scope, e.g., @openedx/frontend-app-authn → frontend-app-authn). Or it could be declared explicitly.

Config shape — refined. Went through several iterations on the key name (openedx, translations, etc.). Settled on atlasTranslations — ties it clearly to atlas, avoids generic names, no extra nesting.

{
  "name": "@openedx/frontend-app-authn",
  "atlasTranslations": {
    "path": "translations/frontend-app-authn/src/i18n/messages",
    "dependencies": ["@openedx/frontend-base"]
  }
}

• path: the FROM path for atlas (what to pull from the translations repo)
• dependencies: npm package names whose translations are also needed (mirrors npm's own terminology)

Decision: use the full package name (with scope) as the TO alias / local directory name. No stripping, no deriving — the pull script already knows the package name, just use it directly. More explicit, avoids name collisions.

Resulting directory structure at the site level:

src/i18n/messages/
├── @openedx/
│   ├── frontend-app-authn/
│   │   ├── ar.json, ...
│   ├── frontend-app-learner-dashboard/
│   │   ├── ar.json, ...
│   ├── frontend-base/
│   │   ├── ar.json, ...
│   └── paragon/
│       ├── ar.json, ...

Atlas pull would use FROM:@openedx/frontend-app-authn for each source. intl-imports (or its replacement) would need to handle scoped directory names.

Design Constraints

• Site operators should not need to think about translations in site config
• Translation wiring should be automatic/invisible to operators
• One pull_translations target at the site level should cover all installed apps + shared libs
• Translations should be deduplicated (e.g., paragon pulled once, not once per app)
• Translation source path convention (translations/{package-name}/src/i18n/messages) is reliable

How does frontend-template-site fit in? The site isn't translatable itself — it has no strings in the translations repo. But it needs to kick off the pull for all installed apps.

Option A: No atlasTranslations on the site. Pull script reads the site's package.json dependencies, checks each for atlasTranslations, follows the chain. Site is the entry point, not a node in the graph. More automatic — install an app, translations come along.

Option B: Site has atlasTranslations.dependencies. Explicitly lists which apps to pull translations for:

{
  "name": "@openedx/frontend-template-site",
  "atlasTranslations": {
    "dependencies": ["@openedx/frontend-app-authn", "@openedx/frontend-app-learner-dashboard"]
  }
}

More explicit, but duplicates what's already in dependencies — conflicts with "operators shouldn't think about translations" constraint.

User concern: Option B means operators maintain translations info in two places (site config + atlasTranslations). But it might be cleaner than tree walking or risking missing things with a shallow dive.

Proposed middle ground: Pull script reads the site's direct dependencies from package.json (a short list, ~10-15 packages), checks each one's node_modules/{pkg}/package.json for atlasTranslations. For any that have it, collect path and follow their dependencies chain recursively. This is:

• Automatic (no duplication for the operator)
• Shallow (only direct deps, not the full tree — trivial to scan)
• Targeted (only follows the atlasTranslations.dependencies chain from there)

Leaning toward option B. Reasoning:

• Scanning direct deps (option A) works for known cases but could cause tricky-to-debug issues if a transitive dep ever needs translations
• The duplication cost is low — adding a line to atlasTranslations.dependencies when installing an app, in the same file you're already editing
• The "operators shouldn't think about translations" constraint was more about site.config.tsx (runtime config), not package.json (which operators edit when installing apps anyway)
• Completely unambiguous — no scanning, no depth questions, no surprises
• Still a tentative decision — to be discussed with the team after thinking through the rest of the design

Site config example (option B):

{
  "name": "@openedx/frontend-template-site",
  "atlasTranslations": {
    "dependencies": [
      "@openedx/frontend-app-authn",
      "@openedx/frontend-app-learner-dashboard"
    ]
  }
}

CLI command for pulling translations. frontend-template-site has no Makefile — it uses the openedx CLI for all scripts. Existing commands are single words or use colons (dev:shell). Decided on openedx translations:pull — follows the colon convention and leaves room for future subcommands (e.g., translations:extract).

translations:pull would:

1. Read the site's package.json → get atlasTranslations.dependencies
2. For each dependency, read node_modules/{pkg}/package.json → get atlasTranslations
3. Recursively follow each package's atlasTranslations.dependencies
4. Collect all unique path values
5. Build and run one atlas pull command with all sources
6. Run intl-imports (or equivalent) to generate JS index files

template-site package.json script:

{
  "scripts": {
    "translations:pull": "openedx translations:pull"
  }
}

How translations work at runtime today. Traced the flow through frontend-base:

1. Each app's App config has a messages property (e.g., authenticated-page/i18n/index.ts — currently a placeholder with mostly empty objects per locale)
2. shell/site.tsx calls addAppMessages() during initialization
3. addAppMessages() iterates all apps in site config, calls mergeMessages(app.messages) for each
4. The merged messages feed into IntlProvider — this is the single integration point

This mechanism already works. The test-site's authenticated-page has a fr-ca entry in its messages placeholder, and it would get picked up at runtime. The problem is just that published npm packages ship with empty placeholders.

The gap: In the template-site model, apps are in node_modules — we can't write translations into them. So translations:pull needs to put translations somewhere the runtime can find them, and they need to get merged in alongside (or instead of) the apps' empty messages.

addAppMessages() isn't enough. It only iterates things in the apps array. frontend-base and paragon aren't apps — they're libraries with translatable UI components. Their translations have no App config to carry them. This isn't just a naming issue — it's a real gap.

Clarifying what atlas pulls vs source strings. Atlas pulls translated strings only (the JSON files from Transifex, keyed by locale). Source/default English strings are embedded in the code via defineMessages() / defaultMessage — react-intl uses those as fallback. app.messages and addAppMessages() are purely about translated strings, not source strings.

How messages work in shell/site.tsx today — two paths:

1. initialize({ messages }) — called first with shell's own messages (from shell/i18n). Calls configureI18n() which sets base messages.
2. addAppMessages() — called on SITE_READY, iterates all apps and merges each app's messages on top.

The app.messages pattern was designed for standalone MFEs. Each app bundles its own translations. But in the site model this is messy:

• Apps are in node_modules, can't write translations into them
• Shared lib translations duplicated across apps
• No single place to manage translation pulling

Decision: site-level pull replaces per-app messages. Cleaner approach:

• One translations:pull command, one set of JSON files at the site level
• Deduplicated across all apps and libs
• Site provides all translations via a single merged object passed to initialize()
• app.messages and addAppMessages() become unnecessary in the site model
• Apps define source strings via defineMessages() in code — that doesn't change

Standalone dev is the same flow. Apps like authn have their own site.config.dev.tsx and run openedx dev — they are a site in dev mode. So openedx translations:pull works the same everywhere: read atlasTranslations from package.json, pull, generate src/i18n/index.ts, feed into initialize(). No separate standalone path needed.

intl-imports role clarified. It runs after atlas pull as part of make pull_translations — turns raw JSON files into a JS module the app can import. Still need this step (or equivalent) in the new model, since the runtime needs a JS/TS module, not raw JSON files.

Two commands, not one. Separating the atlas fetch from the module generation:

• openedx translations:pull — fetches JSON from atlas, then chains into prepare at the end
• openedx translations:prepare — turns the pulled JSON files into a JS/TS module the build can consume

Separating them is useful because:

• You might want to regenerate without re-pulling (e.g., manually edited a JSON file for testing)
• You might want to pull without generating (e.g., just inspecting raw files)
• prepare replaces intl-imports — no need for a separate CLI tool

translations:pull full flow:

1. Read site's atlasTranslations.dependencies
2. Recursively resolve all atlasTranslations configs from those packages
3. Collect all unique path values, build atlas FROM:TO mappings (using package name as TO)
4. Run atlas pull to get JSON files into src/i18n/messages/
5. Run translations:prepare automatically at the end (controlled by --prepare flag, defaults to true; pass --no-prepare to skip)

translations:prepare flow:

1. Scan src/i18n/messages/ for package directories containing JSON files
2. Generate per-package index files (handling scoped package names)
3. Generate main src/i18n/index.ts that exports an array of per-package message objects

Per-package index files (e.g., src/i18n/messages/@openedx/frontend-app-authn/index.ts):

import ar from './ar.json';
import es_419 from './es_419.json';

export default {
  'ar': ar,
  'es-419': es_419,
};

Main src/i18n/index.ts:

import authnMessages from './messages/@openedx/frontend-app-authn';
import paragonMessages from './messages/@openedx/paragon';
import frontendBaseMessages from './messages/@openedx/frontend-base';

export default [
  authnMessages,
  paragonMessages,
  frontendBaseMessages,
];

Why per-package rather than one flat file: With many apps installed, a flat file would be hard to read/debug. Per-package keeps things navigable. The runtime doesn't care — it flattens everything via merge({}, ...array) anyway.

Runtime compatibility: The output matches what configureI18n / mergeMessages already expect (LocalizedMessages[]). No runtime changes needed to consume this.

Runtime integration — keep it simple. The site imports the generated src/i18n/index.ts and passes it to initialize():

import siteMessages from './src/i18n';

initialize({
  messages: siteMessages,
});

Since siteMessages already includes everything (apps + libs + shell), addAppMessages() isn't needed. The existing configureI18n / mergeMessages machinery handles the array merge — no runtime changes required.

Decision: remove app.messages and addAppMessages(). All translations come through initialize({ messages }) from the site-level pull. Cleanup:

• Remove messages from the App type
• Remove addAppMessages() from the runtime
• Remove the addAppMessages() call in shell/site.tsx
• Apps drop their src/i18n/index.js placeholder files

Why package.json for atlasTranslations? Considered a separate file (atlasTranslations.json) but package.json custom fields are an established JS ecosystem pattern (browserslist, babel, eslint, jest, stylelint). Config is only ~3 lines, not worth an extra file. atlas.yml was also considered but that's atlas's own CLI config (repository, revision, filters) — different concern from declaring what a package needs.

Team discussion on site-level translations. Javier pointed out that template-site has translatable text (homeApp). Question: should operators fork openedx-translations for their site strings?

Decision: recommend checking site translations into the site repo. Forking openedx-translations is heavy — huge repo, sync burden, just for a few custom strings. Instead, site operators check their translated JSON files directly into src/i18n/messages/ in their site repo. translations:pull needs to be careful not to blow away site-local files when pulling.

Site-local translations as overrides (Adolfo). If site translations are imported last in the array in src/i18n/index.ts, they "win" the merge — enabling manual translation overrides without forking openedx-translations. This is a nice side effect of the array merge approach.

Lazy loading concern (Adolfo/Javier). Are translations one big chunk or lazy-loadable? Currently one big chunk via initialize({ messages }). Ideally we'd lazy-load only the locale needed. Webpack might chunk it automatically depending on how it's imported. Not a primary concern now — can revisit later if bundle size becomes an issue.

Javier on atlasTranslations config. Looks good, easy to configure. For the mfe-plugin templating approach they'd need an extra config to mark things as translatable.

Separate directories for pulled vs site-local translations:

src/i18n/
├── index.ts              ← generated by translations:prepare
├── site-messages/        ← operator's own translations, checked in
│   ├── ar.json
│   ├── fr.json
│   └── ...
└── messages/             ← generated by translations:pull, gitignored
    └── @openedx/
        ├── frontend-app-authn/
        ├── frontend-base/
        └── paragon/

• messages/ is gitignored — generated from atlas, safe to blow away on pull
• site-messages/ is checked in — operator-managed, never touched by pull
• translations:prepare generates index.ts files for both messages/ and site-messages/, with site-messages last in the array for override behavior
• site-messages/index.ts is gitignored (generated by prepare), but the *.json files are tracked
• If site-messages/ doesn't exist or is empty, prepare skips it gracefully
• This directory structure should be added to frontend-template-site as part of this work

Layer of indirection for operator customization. Instead of prepare generating index.ts directly, it generates messages.ts. index.ts is checked in and operator-controlled:

// src/i18n/index.ts — checked in, operator can customize
export { default } from './messages';

// src/i18n/messages.ts — generated by prepare, gitignored + force-added placeholder
export default [];

Default case: index.ts just re-exports messages.ts — works out of the box.
Custom case: operator edits index.ts to do whatever they need while still importing prepared messages as a starting point.
No-pull case: messages.ts placeholder exports empty array → app works with just defaultMessage strings.

Gitignore + force-add pattern (matches existing convention in apps):

• messages.ts is gitignored but force-added (git add -f) as an empty placeholder
• Fresh clone has the placeholder → app works → prepare overwrites → git ignores the change

Gitignore for site's src/i18n/:

src/i18n/messages.ts
src/i18n/messages/
src/i18n/site-messages/index.ts

Open Questions

• Lazy loading of translations — future optimization, not blocking

Notes

• The atlas-base directory contains:
  • frontend-app-authn
  • frontend-app-learner-dashboard
  • frontend-base
  • frontend-template-site
  • openedx-atlas

[brian-smith-tcril]

My main "not sure about this" thing is where the atlasTranslations config block should live. package.json seems odd but it's a file every package has. app.config and site.config don't make sense because we'll need this for both app and site (and frontend-base itself and paragon which have neither). Another option would be to just add a new file for atlas pull config.

Edit: I think I may be warming up to this as a reasonable place for it

Custom package.json fields are an established JS ecosystem pattern (browserslist, babel, eslint, jest, stylelint). Config is small (~3 lines), not worth a separate file. atlas.yml is for atlas CLI config, not package metadata.