mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-04 10:24:02 +00:00
German KhokhlovandClaude Opus 5.5
7db0abc396
A screenshot review of the Spanish UI found: - Text left in English. Catalog entries copied from English (Bloom, Cyber, Pin, NEWS, SITE, ON/OFF, RANGE, PITCH, HGT…) and the radio music genres, which never went through t(). The genres are translated in es and ru now. - Wording: gender agreement, calques of the English, hints that name buttons that do not exist, and one concept worded two ways. - Layout: the DESACTIVADO pill squeezed layer names until words broke mid-word; the scene and camera selects showed one word; a collapsed rail title pushed its button out of the card; the image slot line and a comparison readout were cut or split. The layout fixes are scoped to languages other than English, so English stays pixel-identical. Visual-style slider values now use the locale's decimal separator (0,85). npm run i18n now reports a translation that is identical to the English, unless src/i18n/same-as-english.json lists it for that language (codes, product names, words spelled the same). Co-Authored-By: Claude Opus 5.5 <[email protected]>
90 lines
7.0 KiB
Markdown
90 lines
7.0 KiB
Markdown
# UI text and translation
|
|
|
|
Every piece of text a user can see goes through `t()`, `tn()` or `msg()` in code, or a `data-i18n*` attribute in markup. The English text itself is the key. English needs no catalog; other languages live in `src/i18n/locales/<code>.json`. Translators work from [TRANSLATORS.md](./TRANSLATORS.md).
|
|
|
|
## Which one to use
|
|
|
|
| | Translates | Use for |
|
|
| ------------------------------- | --------------------------------- | --------------------------------------------- |
|
|
| `t(text, values)` | now | any text shown right where it is written |
|
|
| `tn(count, one, other, values)` | now, picking the form for `count` | text that changes with a number |
|
|
| `msg(text)` | never: returns `text` unchanged | text stored in data and passed to `t()` later |
|
|
|
|
```js
|
|
import { t, tn, msg } from '../i18n/index.js';
|
|
|
|
status.textContent = t('Save keys');
|
|
status.textContent = t('Saved to {store}', { store: storeLabel() });
|
|
|
|
chip.textContent = tn(missing, '{count} KEY WAITING', '{count} KEYS WAITING');
|
|
// en: 1 KEY / 3 KEYS ru: 1 КЛЮЧ / 3 КЛЮЧА / 5 КЛЮЧЕЙ
|
|
|
|
const FEED_STATE_LABELS = { loading: msg('LOADING'), stale: msg('STALE') };
|
|
label.textContent = t(FEED_STATE_LABELS[state]);
|
|
```
|
|
|
|
`msg()` exists for two reasons. `npm run i18n` finds messages only as string literals inside `t(…)`, `tn(…)` and `msg(…)`, so `t(FEED_STATE_LABELS[state])` alone tells it nothing. And a `t()` call at module load runs before the page has picked its language, so it would freeze the English.
|
|
|
|
## Markup
|
|
|
|
```html
|
|
<span data-i18n>Normal</span>
|
|
<button title="Pin visual presets" data-i18n-title>…</button>
|
|
<input placeholder="Search any location..." data-i18n-placeholder />
|
|
```
|
|
|
|
`data-i18n` replaces the element's text, so put it on the element that directly holds the text, never on a parent with child elements. `data-i18n-title`, `data-i18n-aria-label` and `data-i18n-placeholder` translate that attribute. Markup is translated once at boot, and switching language reloads the page.
|
|
|
|
## Rules
|
|
|
|
- **Pass literals.** `t('Close')`, not `t(label)` (unless `label` holds a `msg()` value) and never a template literal with `${…}`.
|
|
- **Use placeholders, not concatenation.** `t('Flying to {place}…', { place })`, not `t('Flying to') + ' ' + place`. Word order differs between languages.
|
|
- **Use `tn()` for counts**, not `count === 1 ? … : …`. Russian has three forms.
|
|
- **Translate the label, not the value.** Layer ids, enums, share-link parameters, API fields, voice tool schemas and feed data (callsigns, vessel and place names) stay as they are; translate only the text shown for them.
|
|
- **No `t()` at module top level.** Keep the English in `msg()` and call `t()` when rendering.
|
|
- **Numbers and dates** go through `formatNumber`, `formatDate` and `formatRelativeTime` from `src/i18n/index.js`, which follow the active language.
|
|
- **Identical English means identical translation,** unless you give it a context: `t('CLEAR', { context: 'action' })` (a button) is its own catalog entry, `action|CLEAR`, while `t('CLEAR')` (the sky) stays separate. English output is the same.
|
|
- **Text that should stay English** (a brand, a code, a unit symbol) is simply not wrapped.
|
|
|
|
## After you add or change text
|
|
|
|
```sh
|
|
npm run i18n # what each language lacks or no longer uses, and unmarked UI text
|
|
npm run i18n -- --missing ru # the missing ru entries as JSON
|
|
npm run i18n -- --prune # drop entries whose English no longer exists
|
|
```
|
|
|
|
Changing the English changes the key, so the old translation goes unused and the new text shows as missing. Add the translation to `src/i18n/locales/ru.json` (or ask a translator), prune, and run `npm test`, which runs the same check and fails until every language is complete.
|
|
|
|
To see a language, open the app with `?lang=ru`, or use the language switch in the Visual Presets dock.
|
|
|
|
A translation that is exactly the English ("Bloom" → "Bloom") is reported as still English. When it is right on purpose, such as a code (HDG, CRT), a product name or a word spelled the same in that language, list it under the language in `src/i18n/same-as-english.json`.
|
|
|
|
## Text the check reports as unmarked
|
|
|
|
`npm run i18n` also lists UI text that is not marked at all, and fails while there is any; `npm test` runs the same check:
|
|
|
|
- **Markup:** element text without `data-i18n`, and `title`, `aria-label` or `placeholder` without the matching `data-i18n-*`.
|
|
- **Code:** string literals that reach the page without `t()`, `tn()` or `msg()`: assigned to `textContent`, `innerText`, `innerHTML`, `title`, `placeholder`; passed to `setAttribute('title' | 'aria-label' | 'aria-valuetext' | 'placeholder' | 'alt', …)`, `createTextNode`, `insertAdjacentHTML`, `showToast`, `toast`, `setHint`, `announce`; or kept in `label:`, `title:`, `tooltip:`, `placeholder:`, `hint:`, `ariaLabel:`, `caption:`, `subtitle:`, `kicker:`, `emptyText:`, `blurb:`, `countLabel:` properties.
|
|
|
|
Fix it by marking the text. When the text must stay as it is, say so where it lives:
|
|
|
|
| Case | How |
|
|
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
| Codes, units, product names in markup (`0.9 dB`, `ADS-B · 1090`, `OpenSky`) | `translate="no"` on the element; it covers everything inside, as in HTML |
|
|
| Markup whose text code sets through `t()` (a status that starts as `OFF`) | `data-i18n-runtime` on the element |
|
|
| A literal in code that is not UI copy (a product name, sample data) | `// i18n-ignore: <reason>` on the line or the line above |
|
|
|
|
Icons (`aria-hidden="true"`, Material Symbols), comments, CSS values and lowercase identifiers are skipped automatically, and so is `src/tools/`, whose text is written for AI clients rather than the page.
|
|
|
|
## Where things live
|
|
|
|
| File | What it holds |
|
|
| ------------------------------- | ------------------------------------------------------------------------------ |
|
|
| `src/i18n/index.js` | `t`, `tn`, `msg`, the Intl formatters, markup translation, switching language |
|
|
| `src/i18n/locale.js` | shipped languages, their names, choosing the language at boot |
|
|
| `src/i18n/locales/<code>.json` | one catalog per language, keyed by English text |
|
|
| `src/i18n/same-as-english.json` | per language, the entries that stay as in English on purpose |
|
|
| `scripts/i18n.mjs` | `npm run i18n`: extracts messages, checks the catalogs, finds unmarked UI text |
|
|
| `src/i18n/catalog.test.mjs` | runs that check under `npm test` |
|