RFC: i18n / Internationalization Support (issue #325)

[Starosdev]

This discussion is a request for feedback on the proposed design for issue #325 -- adding internationalization (i18n) support to the Scrutiny frontend.

#325

---

Summary

Scrutiny currently has no i18n infrastructure. All user-facing strings (~144) are hardcoded in Angular templates and TypeScript pipes. The goal is to add runtime language switching with English, Spanish, and French as the initial languages, and to create a straightforward path for community volunteers to contribute additional translations.

---

Key Design Decisions

Library: @jsverse/transloco

Angular's built-in @angular/localize only supports compile-time locale switching, which means a separate build per language and no in-app language toggle. Transloco supports runtime switching via JSON files loaded over HTTP, which is what we want.

Translation files: nested JSON

Files live at webapp/frontend/src/assets/i18n/{lang}.json. Keys are dot-separated and namespaced by component (e.g., dashboard.subtitle, device_status.failed_smart). This makes the files readable for translators who are not developers.

Language preference: localStorage

Stored client-side. Initialized before first render so there is no flash of untranslated content. Falls back to browser language, then English.

Language switcher: header toolbar

A compact button placed next to the existing theme toggle. Clicking it opens a menu with the available languages.

AI-assisted initial translations

A Node.js script using the Anthropic SDK will generate the initial es.json and fr.json from en.json. The generated files will be reviewed before committing. Community contributors can refine them or add new languages via PR.

Validation in CI

A script checks that every key in en.json exists in all other language files. It runs on every PR, so incomplete translations are caught before merge.

---

What Gets Built

1. TranslocoHttpLoader -- loads JSON files using the configured base href (required for the /web/ mount path)
2. LanguageService -- manages active language, localStorage persistence, and browser language detection
3. LanguageSwitcherComponent -- header button with dropdown menu, following the same module pattern as the existing theme toggle
4. en.json -- canonical English strings across 10 namespaces
5. es.json / fr.json -- AI-generated initial translations, reviewed and committed as a baseline
6. Template annotation -- 8 components converted to use the transloco pipe, prioritized by string density
7. Pipe updates -- DeviceStatusPipe, DeviceHoursPipe, and ThemeToggleComponent updated to return translated strings
8. translate.mjs -- script for generating or refreshing translations via the Anthropic API
9. validate-translations.mjs -- CI script that enforces translation completeness
10. CONTRIBUTING.md section documenting the translation workflow for volunteers

---

Adding a New Language (for community contributors)

1. Copy en.json to {lang_code}.json (ISO 639-1 codes, e.g., de.json for German)
2. Translate the values -- do not translate the keys
3. Preserve placeholders exactly as written: {{ count }}, {{ theme }}
4. Do not translate technical terms: S.M.A.R.T, ZFS, SMTP, WWN, SCT, NVMe, ATA, SCSI
5. Register the new language in LanguageService and LanguageSwitcherComponent
6. Run npm run validate-translations locally to confirm no keys are missing
7. Open a PR targeting develop

---

Questions for the Community

• Are there languages you would like to see prioritized beyond Spanish and French?
• Are there terms or phrases specific to Scrutiny (drive health, S.M.A.R.T attributes, etc.) where standard translations might be unclear or misleading? Any guidance on preferred terminology would help produce better initial translations.
• Does the contributor workflow above seem approachable? Is there anything that would make it easier to submit a translation?
• Any preference on whether the language switcher label shows the language code (EN, ES, FR) or a flag, or the full language name?

All feedback is welcome. Once we have enough input we will move forward with implementation.

[HelioMorri]

I suggest defining language tags according to RFC 4646, whose full format is like this: language-script-region-variant-extension-privateuse, which is obviously too long.

Typically, we would choose only the language and region fields. The language field uses the ISO 639-1 standard, and the region field uses the ISO 3166-1 standard.

For example:

• en-US
• zh-CN

For greater precision, a script field can be added, using the ISO 15924 standard.

For example:

• en-Latn-US represents English - Latin- United States
• zh-Hans-CN represents Chinese - Simplified Chinese- China

[HelioMorri]

I would prefer to provide translation in Chinese, Japanese, and Russian. I am proficient in Simplified Chinese, therefore I would like to undertake the Simplified Chinese translation work.

There are no strict standards for translating computer terminology, and an English word can have several similar but different meanings in different contexts. Therefore, I propose the following:

• Add the following requirement to the translation guidelines: If you cannot ensure the accuracy of a word's translation, please indicate the original English word in parentheses in the translation.
• Add annotations to complex concepts, linking to the corresponding official documentation.
• Restrict namespaces to avoid a single word having multiple meanings on the same page, resulting in a translation that is correct in scenario A but unclear in scenario B. It would be even better if translators could clearly understand which page, section, and term they are translating.
• Simplify the complexity of the translation, as not everyone is familiar with front-end development or has access to a testing environment.

[Starosdev]

Thanks for the detailed feedback, @HelioMorri. Both comments are very useful and touch on things we should get right before implementation begins.

Language codes

Agreed on adopting RFC 4646 with language-region format from the start. Renaming files later would be a breaking change for anyone who has already contributed translations. We will use en-US, es-ES, zh-CN, etc. as the canonical file names. The cost of doing this now is zero and it properly supports regional variants like zh-Hans-CN vs zh-Hant-TW down the road.

Translation platform: Crowdin

Rather than asking contributors to fork the repo and submit PRs with raw JSON files, we are going to use Crowdin (free for open source projects). This addresses several of your concerns directly:

• Translators use a web UI with no git or frontend dev knowledge required
• Crowdin shows each string with its context, page location, and optional screenshots
• It tracks translation progress per language and flags incomplete or changed keys automatically
• It handles review workflows, so translations can be verified before they land in the repo
• It opens PRs to the repo automatically when translations are approved

This means contributors just need a Crowdin account to start translating. No local dev environment, no JSON editing, no PR workflow to learn. Projects like Home Assistant and Uptime Kuma use the same approach successfully.

Scoped translation files

Instead of one large JSON file per language, we will split translations by feature area (dashboard.json, device-detail.json, settings.json, zfs.json, etc.). Transloco supports scoped loading natively. This has two benefits: translators always know which page and section a string belongs to, and the app only loads the translations it needs for the current view.

Pluralization

We will wire up ICU message format support from the start. Strings like device counts and hour durations need proper plural rules, and languages like Chinese and Russian have very different pluralization than English. Retrofitting this later is painful.

Translator guidelines

Incorporating your suggestions into the translation guidelines:

• If the accuracy of a translation is uncertain, include the original English term in parentheses
• Technical terms (S.M.A.R.T, ZFS, SMTP, WWN, NVMe, ATA, SCSI, etc.) should not be translated
• Complex concepts will include annotations linking to relevant documentation where appropriate

Language switcher

On the question of codes vs flags vs names: we will use the native language name (English, Espanol, Francais, etc.). Flags are problematic because many languages span multiple countries. The native name is unambiguous and recognizable to the people who would select it.

Phased rollout

We will convert the highest-visibility components first (dashboard, device detail, settings) and ship that as the i18n foundation. Remaining components will be converted incrementally in follow-up PRs. This keeps each change reviewable and gets the infrastructure merged faster.

Initial languages

Starting with English, Spanish, and French as proposed. We will seed each new language in Crowdin with an AI-generated baseline so translators have something to refine rather than starting from empty strings. Given your offer to handle Simplified Chinese -- we would welcome that as one of the first community-contributed languages once the Crowdin project is set up.