Localisation and translating

[rfwn]

I was searching through the codebase, the docs and the repo, but I couldn't find a guide for adding a region's settings, currencies, classifications, translation keys, etc.
How do I do this? What files I need to change or create, what should my steps be?

[yhay81]

The shortest path is to create a Partner Pack rather than edit all of the core settings separately. A pack is specifically meant to bundle a region's locale, currency, cost catalogues, validation presets, and onboarding defaults.

1. Scaffold a pack:

openconstructionerp pack new my-region

This creates a ready-to-edit folder containing manifest.json, logo.svg, onboarding.yaml, and a README. The full workflow is documented in Partner Packs — Onboarding & Reference Guide.

2. Put the regional defaults in manifest.json. A minimal useful example is:

{
  "slug": "my-region",
  "partner_name": "My Region Construction Pack",
  "default_locale": "xx",
  "additional_locales": { "xx": "locales/xx.json" },
  "default_currency": "XXX",
  "cwicr_regions": ["cwicr-xx-city"],
  "validation_rule_packs": ["existing_rule_pack_slug"],
  "branding": { "primary_color": "#0F2C5F", "logo_path": "logo.svg" },
  "onboarding_script_path": "onboarding.yaml"
}

Use a real ISO-4217 three-letter code for default_currency; the exact fields and constraints are in the manifest reference. The Mexico pack is a good complete example.

3. Add translation overrides under locales/xx.json and map them in additional_locales. Those are served by the pack at runtime. If you want xx to become a fully supported core UI language (not merely a pack override), that is a separate core change: add it to SUPPORTED_LANGUAGES in frontend/src/app/i18n.ts, add frontend/src/app/locales/xx.ts using en.ts as the key baseline, and—if backend messages also need it—add xx to SUPPORTED_LOCALES/LOCALE_NAMES plus backend/locales/xx.json. You can check frontend coverage with:

node frontend/scripts/i18n-diff.cjs frontend/src/app/locales/xx.ts

4. Currency usually needs no core code change: the regional default belongs in the pack and the settings UI accepts a custom three-letter code. If you want it to appear as a curated preset everywhere, add it to currencyGroups.ts and the CURRENCIES list in RegionalSettings.tsx.

5. “Classifications” has two different meanings here:

   • For regional cost catalogues, set cwicr_regions.
   • For validation standards, validation_rule_packs can only enable rule-pack slugs already implemented in core. A Partner Pack cannot introduce new executable rule classes.
   • For a brand-new BOQ classification tree, this is currently a core/module change: ClassificationPicker.tsx hard-codes din276 and nrm. Add the new standard/tree there (or preferably make it data-driven in a dedicated module), then reference/enable it from the pack.

6. Install by dropping the folder/zip into ~/.openestimate/packs/ and using Modules → Partner Packs → Rescan → Activate, or upload the zip in the Partner Packs UI. Activation is reversible.

So: start with a Partner Pack; only touch core for a genuinely new UI language, curated picker entry, executable validation logic, or BOQ classification tree. That keeps the regional contribution small and avoids duplicating defaults across the app.

[rfwn]

Thank you.
Can I say that I want to implement the said stuff into a fork of the project, having the translations and everything else baked in the core, instead of creating a new partner pack. In this case, how should I handle it?

[yhay81]

Yes — in a fork you can make the region a first-class/core feature. A Partner Pack is the lower-maintenance upstream route, but it is not technically required.

I would implement the fork in these layers, in this order:

1. Frontend language

   • Add the language to SUPPORTED_LANGUAGES.
   • Copy frontend/src/app/locales/en.ts to xx.ts and translate every key. The existing dynamic import in i18n.ts will create/load that locale chunk automatically.
   • Check coverage with node frontend/scripts/i18n-diff.cjs frontend/src/app/locales/xx.ts.

2. Backend language (only needed for API errors/messages generated server-side)

   • Add xx to SUPPORTED_LOCALES and LOCALE_NAMES in backend/app/core/i18n.py.
   • Add backend/locales/xx.json, using backend/locales/en.json as the key baseline.
   • Extend the i18n tests (especially backend/tests/unit/test_i18n.py and Accept-Language tests).

3. Regional formats and currency

   • Add the region's number/date format option and curated currency entry in RegionalSettings.tsx.
   • Add the currency to currencyGroups.ts where the project currency groups are defined.
   • Set the desired defaults in your onboarding/seed path. Do not silently rewrite existing projects; currency and locale are persisted preferences/project data.

4. Classification

   • ClassificationPicker.tsx currently defines ClassificationStandard = 'din276' | 'nrm' and embeds both trees. Add your standard to that union, add its tree, and replace the two-way standard === 'nrm' ? ... : ... selection with a map keyed by standard.
   • Then search the whole repository for ClassificationStandard, classification_standard, din276, and nrm; update validation, project/demo seed data, import/export, and any API schema that still assumes only those two values.
   • Extend ClassificationPicker.test.tsx for the new tree and standard.

5. Regional catalogues/rules

   • If these are only data, add them as a core module/dataset and seed them explicitly.
   • If they execute validation logic, implement/register real rule classes; the Partner Pack manifest's validation_rule_packs field only activates rule slugs already implemented in core.

For a maintainable fork, keep those as separate commits (language, formats/currency, classification, datasets/rules) and add a small fork-specific onboarding seed that selects them for new installations. That makes future upstream rebases much less painful and avoids changing existing users' persisted projects unexpectedly.

[rfwn]

Thank you for your detailed answer.

One question though, frontend/src/app/locales/en.ts says:

// Auto-generated from i18n-fallbacks.ts split. Do not edit by hand.
// Regenerate with: node --experimental-strip-types scripts/split-i18n-fallbacks.mjs

This suggests that the first entry point for adding the localization strings is not directly this file (please correct me if I'm wrong). What I mean by this is there must be another file to generate the locales from, am I right?

I appreciate if you explained to me how should I utilize the scripts in my translation workflow.

P.S, also I noticed that there are multiple pipelines mentioning LLMs and other cache stuff related to localization, can you please explain them to me as well?

[yhay81]

You are correct to question that header. I checked the current main files, and the repository is in a post-split architecture where that generated banner is now misleading historical residue.

Today the direction of truth is:

src/app/locales/*.ts → imported by i18n-fallbacks.ts for tests

not the other way around.

The current i18n-fallbacks.ts explicitly describes itself as a test-only aggregator and contains only imports of the per-locale files. Runtime code imports English directly and lazy-loads ./locales/${code}.ts. Meanwhile, split-i18n-fallbacks.mjs calls itself a one-off splitter. Re-running it now imports that aggregator and writes its already-imported locale objects back to disk; it is not a useful authoring source for a new translation and could overwrite manual edits with the currently imported data.

For a new core locale in the current tree, I would use this workflow:

1. Add the language record to SUPPORTED_LANGUAGES in frontend/src/app/i18n.ts.
2. Copy frontend/src/app/locales/en.ts to frontend/src/app/locales/xx.ts. Despite the banner, this new per-locale file is the resource you should edit now.
3. Translate values only. Preserve every key, interpolation such as {{count}}, HTML/Markdown fragments, acronyms, and the flat dotted-key structure.
4. Add a static import for xx and an xx entry to frontend/src/app/i18n-fallbacks.ts. That makes the all-locale tests include it; the runtime dynamic import is handled by the file name plus SUPPORTED_LANGUAGES.
5. Check coverage from the repository root:

node frontend/scripts/i18n-diff.cjs frontend/src/app/locales/xx.ts
node frontend/scripts/i18n-diff.cjs frontend/src/app/locales/xx.ts list-missing
node frontend/scripts/i18n-diff.cjs frontend/src/app/locales/xx.ts list-only-english

6. From frontend/, run npm run typecheck, the relevant Vitest suite, and npm run build.

I would not run split-i18n-fallbacks.mjs during that workflow. Its comment accurately says it was a one-off migration tool; the “Do not edit by hand” header left in the generated locale files should probably be removed or replaced in a separate cleanup commit because it no longer describes the current ownership direction.

The LLM/cache pipeline you noticed is a separate kind of translation. backend/app/core/translation/cascade.py translates runtime construction text (for example a BIM element description) into a regional cost-catalog language for matching. Its order is:

MUSE/IATE lookup → PostgreSQL translation-memory cache → configured LLM → original-text fallback

That pipeline is used by the element-to-CWICR matcher; it does not generate the static i18next UI locale files. The cache prevents repeated LLM calls for the same domain/source/target/text, and the LLM is only a later fallback after terminology tables. The AI-as-judge/eval references in the ADR concern match-quality evaluation/reranking, not UI-string localization.

So keep the two workflows separate: reviewed locales/xx.ts files for product UI, and the backend cascade for user/catalog content at runtime. That makes translation changes reproducible and prevents a model/cache result from silently becoming shipped interface text.

[datadrivenconstruction]

yhay81 has this right. I checked it against the code and it holds, so I have marked it as the answer.

Two things to add. The manifest has more fields than the example shows, so use MANIFEST_REFERENCE.md as the list. And there are 29 locale files now, not the 27 our docs still say.

You were right that nothing tells you where to start. That is our gap and we will write that page.