Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(ok): offer the six remaining LTR interface locales (PRD-7864) (#3344)

Andrew Mikofalvyae918ab30cda
diff --git a/.changeset/ship-remaining-interface-locales.md b/.changeset/ship-remaining-interface-locales.md
new file mode 100644
index 000000000..6ad2c8863
--- /dev/null
+++ b/.changeset/ship-remaining-interface-locales.md
@@ -0,0 +1,11 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+**Settings → Preferences → Language** now offers nine languages instead of three. 繁體中文, हिन्दी, Français, বাংলা, Português do Brasil and Indonesia join English, Español and 简体中文 in the picker, and the app will follow your operating system into any of them.
+
+These catalogs were always complete — the six new ones have been shipping fully translated since language selection landed, just with no way to select them. They were held back until a native speaker had read them, which turned out to be the wrong way round: the people who could tell us a translation reads badly were exactly the people who never encountered it. So they ship, and we say plainly that most of them have not been read.
+
+That last part is not a formality. Of the nine, only English (the source) and Español have been through someone who reads the language. The rest, 简体中文 included, are a machine's best guess against a locked glossary. If you read one of them and something is wrong — a word that no one would actually use, a sentence that parses but does not land — [it takes one pull request to fix](https://openknowledge.ai/docs/contribute/translations), and that is now the only way it gets fixed.
+
+العربية and اردو stay out of the picker. Their catalogs are complete too, but the interface's right-to-left layout is unfinished: some labels stay left-aligned, some arrows keep pointing the way they did, and section headings are letter-spaced in a way that pulls Arabic apart at the joins. Both remain selectable by hand via `appearance.language` so a contributor can still check the words, and the app will not drop you into either from your OS language alone.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3a25ff845..65761e819 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,7 +5,7 @@ Thanks for contributing! Bug reports, feature requests, and pull requests are al
- **Found a bug or have an idea?** [Open an issue](https://github.com/inkeep/open-knowledge/issues/new/choose).
- **Question or setup help?** Ask in [Discord](https://discord.gg/VRKk2EaGHN).
- **Ready to code?** Open a pull request against this repository.
-- **Read a language other than English?** Most of our interface translations are machine-translated and have never been read by a native speaker. Reviewing one is what makes it selectable in the app — see [Translate the interface](https://openknowledge.ai/docs/contribute/translations).
+- **Read a language other than English?** Most of our interface translations are machine-translated and have never been read by a native speaker, and we ship them anyway rather than hide them from the people who could fix them. Correcting one is the most useful thing you can do for it — see [Translate the interface](https://openknowledge.ai/docs/contribute/translations).
## Development setup
diff --git a/docs/content/contribute/translations.mdx b/docs/content/contribute/translations.mdx
index 9d4ee469d..7cd548795 100644
--- a/docs/content/contribute/translations.mdx
+++ b/docs/content/contribute/translations.mdx
@@ -1,26 +1,26 @@
---
title: Translate the interface
icon: LuLanguages
-description: Review one of our machine-translated interface languages and make it selectable in the app.
+description: Read one of our machine-translated interface languages and correct what a machine got wrong.
---
-OpenKnowledge's interface exists in eleven languages. A few of them are offered in **Settings → Preferences → Language**; the rest were machine-translated and nobody who reads them has checked them yet.
+OpenKnowledge's interface exists in eleven languages, nine of them offered in **Settings → Preferences → Language**. Ten were translated by a machine, and only one of those ten has had a native speaker read it.
-Closing that gap is what this page is asking for. If you read one of the unreviewed languages, a review pass over its translations is the most useful thing you can do for it, and it is what moves that language into the picker.
+Correcting one is what this page is asking for. If you read one of the other nine, a pass over its translations is the most useful thing you can do for it.
Which language is in which state lives in the `appearance.language` row of the [configuration reference](/docs/reference/configuration#schema). That table is the source of truth, so this page doesn't repeat it.
-## Review is the bar, not completeness
+## What is actually wrong with them
Completeness is not the gap. Every language already has a translation for every string in the interface, and a change that adds a new string is refused unless it translates that string into every language in the same change. Nothing is blank, the placeholders line up, the plural forms are all present.
What machine translation does not reliably produce is prose that reads naturally and terminology a user of that language would actually recognize. No test we can write sees that failure, and neither can anyone here. Only a reader of the language does.
-So the question that decides whether a language appears in the picker is not whether its catalog is full — they all are. It is whether someone who reads that language has read it. Offering a language in the picker says we stand behind it, and for most of them nobody here can. When a native speaker reviews a catalog and we merge that review, the language goes into the picker.
+We used to hold a language out of the picker until a native speaker had read it. That turned out to be backwards: the people who could tell us a translation was wrong were exactly the people who never met it, because it wasn't offered to them. So they ship, and we say plainly which ones a human has read — today that is English, which is the source, and Español. Everything else is a machine's best guess sitting in front of users who deserve better, which is why a correction is worth sending even if it is one word.
## Run OpenKnowledge in the language you're checking
-You don't have to wait for a language to be promoted to see it. Set it by hand in `~/.ok/global.yml`:
+Nine languages are one click away in **Settings → Preferences → Language**. For the two that aren't, or if you'd rather not click, set it by hand in `~/.ok/global.yml`:
```yaml
appearance:
@@ -29,10 +29,12 @@ appearance:
Any of the eleven works here, in the picker or not. That is deliberate — a translator has to be able to look at their own work. Use the tag exactly as it appears in the configuration reference (`zh-Hans`, `pt-BR`, and so on). The editor picks the change up without a restart.
+Reading the interface in your own language is the best review there is, and the one nobody here can do for you.
+
On the desktop app, the `OK_LANG` environment variable additionally overrides the **native menus** for a single run, which is the quickest way to check menu translations without touching config. The rest of the window follows `appearance.language`, so set both if you want everything in one language at once.
<Callout type="warn" title="Arabic and Urdu are a special case">
-`ar` and `ur` have full, maintained translations, but the interface still lays itself out left to right. Until right-to-left layout is built, the words will be right and everything around them will be wrong, and there is no useful way to review the result visually. Corrections to the text are still welcome; a layout review isn't possible yet.
+`ar` and `ur` have full, maintained translations and are the two languages the picker doesn't offer. Setting one by hand does flip the interface to right-to-left, and most of the layout follows, but the sweep isn't finished: some labels stay left-aligned, some arrows and chevrons keep pointing the way they did, spacing lands on the wrong side in places, and section headings are letter-spaced in a way that pulls Arabic apart at the joins. Corrections to the *text* are as welcome as for any other language — just don't spend your time reporting the layout, which we already know about.
</Callout>
## Make the change
@@ -55,7 +57,7 @@ packages/app/src/locales/<locale>/messages.po
Commit both files.
-4. **Open a pull request.** Say which language you reviewed and whether you speak it natively. That is the part we can't get any other way, and it is what promotes the language.
+4. **Open a pull request.** Say which language you read and whether you speak it natively. That is the part we can't get any other way, and it's what lets us stop describing the language as unread.
[CONTRIBUTING.md](https://github.com/inkeep/open-knowledge/blob/main/CONTRIBUTING.md) covers the rest: toolchain, `pnpm run check`, and the Contributor License Agreement.
diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdx
index db07062db..7367ebab4 100644
--- a/docs/content/reference/configuration.mdx
+++ b/docs/content/reference/configuration.mdx
@@ -37,7 +37,7 @@ A key set in a file more specific than its scope (a user-scope key in `.ok/confi
| `contentRules.frontmatter.enabled` | boolean | `false` | project | Enable the [Frontmatter schemas](/docs/advanced/content-rules/frontmatter) content-rules plugin for this project (shared via git). Off by default — turn it on in **Settings → This project → Plugins**. |
| `contentRules.frontmatter.schemas` | array | `[]` | project | Frontmatter schema mappings: each entry scopes one JSON Schema file to a set of docs — `file` (project-root-relative path), optional `appliesTo` (glob or list; leading `!` excludes; absent means every doc), optional `enabled: false` to park a mapping. Schema content lives in the mapped files, not here. See [Frontmatter schemas](/docs/advanced/content-rules/frontmatter). |
| `appearance.theme` | `"light" \| "dark" \| "system"` | (unset) | user | Editor light/dark theme. |
-| `appearance.language` | `"system" \| "en" \| "zh-Hans" \| "zh-Hant" \| "hi" \| "es" \| "ar" \| "fr" \| "bn" \| "pt-BR" \| "id" \| "ur"` | (unset) | user | Interface language. `system` (the effective value when unset) follows your operating system or browser, and keeps following it. A personal preference, not project-shared — and it applies to the app's own chrome only: your documents, titles, file and folder names, frontmatter values and tags stay in the language you wrote them in. **Settings → Preferences → Language** offers the reviewed set (English, Español, 简体中文); the other locales are machine-translated and awaiting a native review, so they are set here by hand rather than picked, and `ar` / `ur` additionally wait on right-to-left layout work — the app will not select either from your OS language alone. `OK_LANG=<tag>` overrides the desktop app's native menus for a single run; the rest of the interface follows this field. Reviewing one of the machine-translated locales is what promotes it into the picker — see [Translate the interface](/docs/contribute/translations). |
+| `appearance.language` | `"system" \| "en" \| "zh-Hans" \| "zh-Hant" \| "hi" \| "es" \| "ar" \| "fr" \| "bn" \| "pt-BR" \| "id" \| "ur"` | (unset) | user | Interface language. `system` (the effective value when unset) follows your operating system or browser, and keeps following it. A personal preference, not project-shared — and it applies to the app's own chrome only: your documents, titles, file and folder names, frontmatter values and tags stay in the language you wrote them in. **Settings → Preferences → Language** offers nine of them (English, 简体中文, 繁體中文, हिन्दी, Español, Français, বাংলা, Português do Brasil, Indonesia). Every catalog is complete, but only `es` has been through a Spanish reader; the rest, `zh-Hans` included, are machine-translated and nobody who reads them has checked the wording. Treat it as provisional and [tell us what is wrong](/docs/contribute/translations). `ar` and `ur` are complete translations too, but they stay out of the picker until the interface lays out right to left; set either here by hand to run the app in it, and note the app will not select them from your OS language alone. `OK_LANG=<tag>` overrides the desktop app's native menus for a single run; the rest of the interface follows this field. |
| `appearance.colorThemeLight` | `"default" \| "dracula" \| "catppuccin-frappe" \| "catppuccin-latte" \| "monokai" \| "gruvbox" \| "solarized" \| "custom"` | (unset) | user | IDE color palette applied while the resolved mode is light. `default` (the effective value when unset) means no palette — the base stylesheet shows through. `custom` applies `appearance.customTheme`. Pick it in **Settings → Plugins → Themes** with the tile's sun. |
| `appearance.colorThemeDark` | `"default" \| "dracula" \| "catppuccin-frappe" \| "catppuccin-latte" \| "monokai" \| "gruvbox" \| "solarized" \| "custom"` | (unset) | user | IDE color palette applied while the resolved mode is dark — the tile's moon. `appearance.theme` chooses between the two; on `system` your OS does, so the palette follows the OS appearance. Any palette may sit in either slot, and it keeps forcing its own light/dark variant. |
| `appearance.colorTheme` | `"default" \| "dracula" \| "catppuccin-frappe" \| "catppuccin-latte" \| "monokai" \| "gruvbox" \| "solarized" \| "custom"` | (unset) | user | Legacy single-palette field, superseded by `colorThemeLight` / `colorThemeDark` above. When set, it supplies the palette for whichever of those two slots is unset, so one palette applies in both modes. Writing either slot from **Settings → Plugins → Themes** removes this key. |
diff --git a/packages/app/src/components/settings/SettingsDialogBody.dom.test.tsx b/packages/app/src/components/settings/SettingsDialogBody.dom.test.tsx
index 1b9185264..e619a281c 100644
--- a/packages/app/src/components/settings/SettingsDialogBody.dom.test.tsx
+++ b/packages/app/src/components/settings/SettingsDialogBody.dom.test.tsx
@@ -5,6 +5,7 @@ import {
type ConfigBinding,
type ConfigPatch,
ConfigSchema,
+ LAYOUT_DEFERRED_LOCALES,
PICKER_LOCALES,
} from '@inkeep/open-knowledge-core';
import { act, cleanup, render, screen, waitFor, within } from '@testing-library/react';
@@ -320,25 +321,30 @@ describe('SettingsDialogBody language picker', () => {
expect(fields.indexOf('appearance.language')).toBe(fields.indexOf('appearance.theme') + 1);
});
- test('offers the reviewed picker set and none of the enumerated rest', async () => {
+ test('names each language in itself, and offers none that is held back', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
renderPreferences(binding);
await openLanguagePicker(user);
- expect(screen.getAllByRole('option').map((el) => el.textContent)).toEqual([
- 'System',
- 'English',
- 'español',
- '简体中文',
- ]);
- // Hindi is enumerated in the config schema but has had no native review, so
- // it must not be reachable from the picker.
- expect(screen.queryByRole('option', { name: 'हिन्दी' })).toBeNull();
+ // Named in their own language, so someone who cannot read the language on
+ // screen can still find theirs. Membership is the sibling test below; this
+ // one is about what the rows say.
+ const names = screen.getAllByRole('option').map((el) => el.textContent);
+ expect(names[0]).toBe('System');
+ expect(names).toContain('简体中文');
+ expect(names).toContain('português (Brasil)');
+
+ // The two right-to-left locales are enumerated and complete, and must stay
+ // unreachable from here while the chrome's layout for them is unfinished.
+ for (const locale of LAYOUT_DEFERRED_LOCALES) {
+ const endonym = new Intl.DisplayNames([locale], { type: 'language' }).of(locale);
+ expect(screen.queryByRole('option', { name: endonym })).toBeNull();
+ }
});
- test('derives its locale options from the reviewed set in core', async () => {
+ test('derives its locale options from the offered set in core', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
renderPreferences(binding);
@@ -381,16 +387,19 @@ describe('SettingsDialogBody language picker', () => {
});
});
- test('a hand-set unpromoted locale still shows, without becoming an option', async () => {
+ test('a hand-set withheld locale still shows, without becoming an option', async () => {
const user = userEvent.setup();
- const config = ConfigSchema.parse({ appearance: { language: 'hi' } });
+ const config = ConfigSchema.parse({ appearance: { language: 'ar' } });
const { binding } = makeBinding(config);
renderPreferences(binding);
- expect(screen.getByRole('combobox', { name: 'Language' }).textContent).toContain('हिन्दी');
+ // The trigger renders its own label rather than mirroring a selected item,
+ // which is what keeps a preference the picker does not list from showing as
+ // an empty control.
+ expect(screen.getByRole('combobox', { name: 'Language' }).textContent).toContain('العربية');
await openLanguagePicker(user);
- expect(screen.queryByRole('option', { name: 'हिन्दी' })).toBeNull();
+ expect(screen.queryByRole('option', { name: 'العربية' })).toBeNull();
});
});
diff --git a/packages/app/src/lib/use-apply-config-language.dom.test.tsx b/packages/app/src/lib/use-apply-config-language.dom.test.tsx
index 47671189c..9ba856f07 100644
--- a/packages/app/src/lib/use-apply-config-language.dom.test.tsx
+++ b/packages/app/src/lib/use-apply-config-language.dom.test.tsx
@@ -17,11 +17,7 @@
* hook.
*/
-import {
- LAYOUT_DEFERRED_LOCALES,
- type LanguagePreference,
- PICKER_LOCALES,
-} from '@inkeep/open-knowledge-core';
+import { LAYOUT_DEFERRED_LOCALES, type LanguagePreference } from '@inkeep/open-knowledge-core';
import { act, cleanup, render, waitFor } from '@testing-library/react';
import { afterEach, beforeAll, describe, expect, test } from 'vitest';
import { dynamicActivate } from './activate-locale';
@@ -132,16 +128,6 @@ describe('useApplyConfigLanguage', () => {
expect(i18n.locale).toBe('fr');
});
- test('a language nobody has reviewed yet still activates', async () => {
- // The picker withholds these; a stored value must not, or a translator
- // cannot run the app in the language they are translating.
- expect(PICKER_LOCALES).not.toContain('zh-Hant');
-
- await renderHarness('zh-Hant', true);
-
- expect(i18n.locale).toBe('zh-Hant');
- });
-
test('the bootstrap catalog stands until the user layer has loaded', async () => {
// An absent preference and an unloaded one look identical on the value
// alone. Acting on the unloaded one activates the browser's language on
@@ -178,9 +164,10 @@ describe('useApplyConfigLanguage', () => {
});
test('the browser alone cannot put the chrome in a language it cannot lay out', async () => {
- // The chrome still uses physical margins and insets, so right-to-left is
- // visibly wrong. An Arabic browser with nothing stored is a guess, and this
- // is not a guess worth making on someone's behalf.
+ // Right-to-left mirrors most of the shell but leaves defects the chrome has
+ // not been swept for — `REVIEW.md` carries the inventory. An Arabic browser
+ // with nothing stored is a guess, and this is not a guess worth making on
+ // someone's behalf.
expect(LAYOUT_DEFERRED_LOCALES).toContain('ar');
stubBrowserLanguages(['ar-EG', 'fr-CA']);
diff --git a/packages/app/src/locales/GLOSSARY.md b/packages/app/src/locales/GLOSSARY.md
index 0a52887e9..55d5a9992 100644
--- a/packages/app/src/locales/GLOSSARY.md
+++ b/packages/app/src/locales/GLOSSARY.md
@@ -14,8 +14,7 @@ each time.
Eight nouns is deliberately small — under a hundred cells against ~2,800 catalog entries per
locale. It is the one artifact in this system short enough for a native speaker to review end
to end, which is what makes it worth more than the same effort spread over the catalogs.
-That review, and what it takes to get a locale into the language picker, is
-[`REVIEW.md`](./REVIEW.md).
+That review, and which locales have actually had one, is [`REVIEW.md`](./REVIEW.md).
## Never translated
diff --git a/packages/app/src/locales/REVIEW.md b/packages/app/src/locales/REVIEW.md
index 40f0be74d..8920a4e09 100644
--- a/packages/app/src/locales/REVIEW.md
+++ b/packages/app/src/locales/REVIEW.md
@@ -1,16 +1,23 @@
# Locale review and promotion
-OpenKnowledge enumerates eleven interface locales and offers three of them in the language
-picker. The other eight have complete catalogs that nobody can select. That gap is deliberate,
-and this file is how a locale crosses it.
+OpenKnowledge enumerates eleven interface locales and offers nine of them in the language
+picker. The two it withholds are withheld for a layout reason, not a translation one. This file
+records which of the nine a reader of the language has actually read, which is a different
+question from which ones are offered, and it is the file to update when that changes.
-Completeness is not the bar. Every catalog in `src/locales/` is full, because the agent that
-writes a string writes its ten translations in the same change. What ten of them have not had is
-a reader — someone who reads the language telling us the words are right. Offering a language in
-the picker is standing behind it, and we can only stand behind what someone has read.
+Completeness is not the bar and never was. Every catalog in `src/locales/` is full, because the
+agent that writes a string writes its ten translations in the same change. What most of them
+have not had is a reader — someone who reads the language telling us the words are right.
-So: **a locale enters the picker when someone who reads it has reviewed it.** Nothing else
-promotes one. Not 100% coverage, not a green CI run, not another model agreeing with the first.
+**Being unread does not hold a language back from the picker.** It used to, and the effect was
+backwards: the people who could tell us a translation was wrong were the same people who could
+never encounter it, because it was not offered to them. So the nine ship, they ship labelled as
+machine-translated where that is what they are, and corrections come back through
+[the translation page](https://openknowledge.ai/docs/contribute/translations) as ordinary pull
+requests.
+
+What that does not do is let us claim they are reviewed. The table below is the whole of that
+claim, and most rows say `unreviewed` for as long as that is true.
## The state of each locale
@@ -30,29 +37,60 @@ promotes one. Not 100% coverage, not a green CI run, not another model agreeing
`source` is the catalog whose `msgstr` is the English text itself; there is nothing to review.
-`unreviewed` is a complete, machine-checked catalog no native reader has seen. Eight of eleven.
+`unreviewed` is a complete, machine-checked catalog no native reader has seen. Eight of eleven,
+and six of those eight are offered in the picker anyway. That pairing is the honest state of
+this project's interface translations and the reason this file exists.
`reviewed` is the bar this file describes: someone who reads the language read it and said so
where a stranger can find it. **No locale holds this status yet.** The first one to earn it will
-be the first promotion this process actually produced.
+be the first review this process actually produced.
-`vouched` is weaker, and exists so the two locales that shipped in the picker before this process
+`vouched` is weaker, and exists so the two locales that shipped in the picker before this file
did are recorded truthfully rather than rounded up. Neither has had a native review; each was
offered for a stated reason that is not one. Recording it this way is not an accusation, it is
the point of having a record: `zh-Hans` in particular is the locale most likely to have real
users and the one with no reader, which makes it the obvious first packet to send out.
-A **blocker** is a reason the locale cannot be offered even with a clean review. Both current
-blockers are the same one: the chrome still lays out with physical margins and insets rather than
-logical ones, so a right-to-left base direction over it is visibly wrong rather than merely
-unpolished. That is a layout problem no translation fixes, and it is deferred until an
-Arabic- or Urdu-reading user or contributor appears. Their catalogs stay complete and
-freshness-gated in the meantime.
-
-Those two are also the reason the packet is a file rather than an instruction to run the app: a
-contributor who opened OpenKnowledge in Arabic today would be looking at a broken layout, so
-"run it in your language and tell us how it reads" is advice that works for eight locales and
-fails for the two that need it most. A packet works for all ten.
+A **blocker** is a reason the locale cannot be offered however good its catalog is. Both current
+blockers are the same one, and it is about layout rather than words. Their catalogs stay
+complete and freshness-gated in the meantime.
+
+## The right-to-left blocker, in detail
+
+`ar` and `ur` are complete and correct as text. What is not finished is the chrome around the
+text. Setting `dir="rtl"` does mirror most of it — the shell is flex and grid, which follow the
+writing mode without being asked, and user-authored text isolates via `dir="auto"` so filenames
+and document bodies keep their own direction. What remains, measured against a running app with
+`appearance.language: ar` and `<html dir="rtl">`:
+
+- **Text that stays left-aligned inside a right-to-left pane.** `text-left` sits outside the
+ logical-property lint rule's scope by design, and forty-odd uses survive in the chrome. Six
+ computed to `text-align: left` on the document surface alone — the same six as in English,
+ which is what makes them wrong rather than incidental.
+- **`ml-auto` spacers that push the wrong way.** They mean "shove this to the far end of the
+ row", which under `rtl` becomes the near end. Trailing affordances land beside their labels
+ instead of opposite them.
+- **Arrows, chevrons and disclosure triangles that do not mirror.** They are static icons, so a
+ right-pointing chevron keeps pointing right when forward has become left. The panel-collapse
+ control is the one you see first; there are around 150 directional icon uses in the chrome.
+- **`tracking-*` on section headings.** The most visible defect, and the one least about
+ direction: 0.7px of letter-spacing on `الملفات`, `الخصائص`, `المخطط` and every command-palette
+ group heading pulls Arabic apart at the joins, which for a cursive script is not a spacing
+ change but a rendering fault.
+- **Physical margins and padding landing on the far side.** Small individually, systematic in
+ aggregate.
+- **The Electron menu bar**, built in the main process, with no direction handling at all.
+
+A green `pnpm check` is not evidence against any of this. The logical-property lint rule carries
+a documented pre-rule backlog — a file-level `biome-ignore-all` on the 81 chrome files that
+predate it, covering around 148 utilities — and the shadcn primitives under `components/ui/` are
+exempt from it entirely while holding well over a hundred physical utilities of their own. The
+rule is a ratchet on new code, not a statement about the code already there.
+
+None of that is a reason not to review the words. It is a reason not to offer the language while
+the layout renders them wrongly, and it is why the packet below is a file rather than an
+instruction to run the app: a contributor who opened OpenKnowledge in Arabic today would spend
+the hour on defects that are not theirs.
This table is parsed, not just read: `scripts/generate-locale-review-packet.mjs` refuses to build
a packet for a locale with no row here, and `scripts/generate-locale-review-packet.test.mjs` pins
@@ -77,9 +115,9 @@ strings first. Asking for 2,900 gets the request declined or skimmed, and a skim
everything is worth less than a real review of the part that matters. The script's header states
the rule; so does the packet, so the reviewer knows what they are being handed.
-A contributor who *can* run the app should also run it in their language — `OK_LANG=fr ok start`
-activates any enumerated locale, promoted or not. That is a better review than the packet. The
-packet exists so that not being able to do it is not a blocker.
+A contributor who *can* run the app should also run it in their language — the picker offers
+nine of them directly, and `OK_LANG=ar ok start` activates the other two. That is a better
+review than the packet. The packet exists so that not being able to do it is not a blocker.
### 2. Send it out
@@ -99,7 +137,7 @@ the catalog holding two words for one concept, which is worse than either word a
Update this file's table in the same PR: `Status` to `reviewed`, `Basis` to the reviewer's name or
handle, `Evidence` to something a stranger can follow back — a PR number, an issue link, a thread.
-"An agent reviewed it" is not evidence and does not count; the entire reason this process exists
+"An agent reviewed it" is not evidence and does not count; the entire reason this record exists
is that a model checking another model's translation tells us nothing new.
A review that comes back with corrections is still a review. What decides the status is that a
@@ -109,33 +147,29 @@ reader of the language read it, not that they had nothing to say.
`src/locales/` against the index, so an unstaged edit to this file or to `GLOSSARY.md` is
reported as catalog drift and sends you off to re-run an extractor that will change nothing.
-## Promoting a locale
-
-One line, in `packages/core/src/i18n/locales.ts` — adding the tag to the tuple. Promoting `fr`
-would read:
-
-```ts
-export const PICKER_LOCALES = ['en', 'es', 'zh-Hans', 'fr'] as const satisfies readonly SupportedLocale[];
-```
+## Offering a locale
-That is the whole change. Everything downstream derives from that tuple:
+One line, in `packages/core/src/i18n/locales.ts` — adding the tag to `PICKER_LOCALES`. Everything
+downstream derives from that tuple:
- The Settings picker renders `PICKER_LOCALES`, so the language appears with no UI edit.
-- `scripts/check-i18n-picker-completeness.mjs` reads the same tuple and starts gating the new
- locale absolutely — a picker entry backed by a partial catalog fails CI from that commit on.
+- `scripts/check-i18n-picker-completeness.mjs` reads the same tuple and gates the new locale
+ absolutely — a picker entry backed by a partial catalog fails CI from that commit on.
- `packages/app/tests/meta/supported-locales-sync.test.ts` already pins `SUPPORTED_LOCALES`
against the Lingui config, so the catalog behind the tuple is guaranteed to exist.
-Ship it with the table update in the same PR, so the picker and the record of why it changed
-arrive together.
+The tuple is pinned equal to the enumerated set minus `LAYOUT_DEFERRED_LOCALES`, so in practice
+a locale is offered as soon as it is enumerated and carries no blocker. Holding a new one back
+means recording a blocker for it, in the table and in the tuple, where a reader can see what the
+reason is.
-A locale carrying a blocker does not get this change, however clean its review. Record the
-review, leave the blocker, and promote when the blocker lifts — a reviewed Arabic catalog behind
-a layout that renders it wrongly is still not something to offer anyone.
+Recording a review is the separate change described above, and it moves the picker in neither
+direction: an unreviewed locale is already offered, and a review that comes back with
+corrections is a request for edits rather than a removal. A reader telling us the language is
+not usable as it stands is the one answer worth acting on that way, and worth writing down.
## Adding a locale nobody asked for
-Don't. Every enumerated locale costs a translation on every new string, forever, and buys nothing
-until someone reads it. The eight unpromoted catalogs are already more than the review capacity
-this project has; adding a twelfth makes the ratio worse, not better. The signal worth acting on
-is a person who wants the language and will read it.
+Don't. Every enumerated locale costs a translation on every new string, forever. Eleven is
+already more than the review capacity this project has; adding a twelfth makes the ratio worse,
+not better. The signal worth acting on is a person who wants the language and will read it.
diff --git a/packages/app/tests/stress/language-picker.e2e.ts b/packages/app/tests/stress/language-picker.e2e.ts
index 4c0ae4e41..4f210bd47 100644
--- a/packages/app/tests/stress/language-picker.e2e.ts
+++ b/packages/app/tests/stress/language-picker.e2e.ts
@@ -89,7 +89,11 @@ test.describe('language picker', () => {
await expect(trigger).toHaveText('System');
});
- test('offers only the reviewed locales', async ({ page }) => {
+ // The literal list is the point: it is what a user sees, spelled the way they
+ // see it, and it is the one place a promotion has to be stated rather than
+ // derived. Deriving the names from `Intl.DisplayNames` here would only agree
+ // with the component for the same reason, and say nothing.
+ test('offers every locale whose layout is finished, each named in itself', async ({ page }) => {
// Drive to English first: the sentinel's label is translated, so the exact
// list below only holds in one locale and this test would otherwise pass or
// fail on whatever the test before it left stored.
@@ -98,6 +102,19 @@ test.describe('language picker', () => {
await expect(page.locator('html')).toHaveAttribute('lang', 'en', { timeout: 10_000 });
await openLanguagePicker(page);
- await expect(page.getByRole('option')).toHaveText(['System', 'English', 'español', '简体中文']);
+ // `ar` and `ur` are absent: enumerated, complete, and held back until the
+ // chrome lays out right to left.
+ await expect(page.getByRole('option')).toHaveText([
+ 'System',
+ 'English',
+ '简体中文',
+ '繁體中文',
+ 'हिन्दी',
+ 'español',
+ 'français',
+ 'বাংলা',
+ 'português (Brasil)',
+ 'Indonesia',
+ ]);
});
});
diff --git a/packages/core/src/i18n/locales.test.ts b/packages/core/src/i18n/locales.test.ts
index 409532cde..1d96d82c0 100644
--- a/packages/core/src/i18n/locales.test.ts
+++ b/packages/core/src/i18n/locales.test.ts
@@ -37,10 +37,25 @@ describe('SUPPORTED_LOCALES', () => {
});
describe('PICKER_LOCALES', () => {
- test('offers only enumerated locales, and not all of them', () => {
+ test('offers only enumerated locales', () => {
const enumerated = new Set<string>(SUPPORTED_LOCALES);
expect(PICKER_LOCALES.filter((tag) => !enumerated.has(tag))).toEqual([]);
- expect(PICKER_LOCALES.length).toBeLessThan(SUPPORTED_LOCALES.length);
+ });
+
+ // The only reason to withhold an enumerated locale is a layout that renders
+ // it wrongly. Not being read is not one — a language nobody can select is a
+ // language nobody can correct.
+ test('withholds exactly the locales whose layout is unfinished', () => {
+ const held = new Set<string>(LAYOUT_DEFERRED_LOCALES);
+ expect(PICKER_LOCALES).toEqual(SUPPORTED_LOCALES.filter((tag) => !held.has(tag)));
+ });
+
+ // Order is what the Settings picker renders, and it reads as a ranking. The
+ // enumerated order is by total speakers, which is a reason; any other order
+ // is an accident of when each locale was promoted.
+ test('keeps the enumerated order', () => {
+ const positions = PICKER_LOCALES.map((tag) => SUPPORTED_LOCALES.indexOf(tag));
+ expect(positions).toEqual([...positions].sort((a, b) => a - b));
});
});
diff --git a/packages/core/src/i18n/locales.ts b/packages/core/src/i18n/locales.ts
index 7518e6c82..19c855ddc 100644
--- a/packages/core/src/i18n/locales.ts
+++ b/packages/core/src/i18n/locales.ts
@@ -41,33 +41,53 @@ export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
/**
* The locales offered in the Settings language picker.
*
- * Deliberately narrower than `SUPPORTED_LOCALES`: enumerated and selectable are
- * different states. A locale is enumerated from day one so the resolver, the
- * matcher and the font stack are exercised against the whole set instead of
- * being retrofitted, and it becomes selectable only once someone who reads it
- * has reviewed its catalog. Completeness is not the bar and never was: every
- * catalog here is full, and the ones outside this list are full of prose no
- * native speaker has read yet. Offering one is standing behind it.
+ * Every enumerated locale whose chrome layout is finished, which today is all
+ * of them but the two right-to-left ones.
*
- * A stored preference naming an enumerated-but-unpromoted locale stays valid
- * and resolves normally — that is what lets a translator run the app in their
- * own language to check their own work.
+ * A complete catalog is what earns a place here. Being unread does not hold a
+ * language back: nobody on this project reads most of these, so waiting for a
+ * native review before offering one means the people who could correct it can
+ * never encounter it in the first place. Shipping it is what puts it in front
+ * of the readers it needs, and corrections come back through the public
+ * translation page rather than through a gate nobody can open.
*
- * Adding a tag to this tuple is the whole of a promotion; the picker, the
- * completeness gate and the review record all derive from it. What has to
- * happen first, and what gets recorded, is
- * `packages/app/src/locales/REVIEW.md`.
+ * What that does not do is turn machine translation into reviewed translation.
+ * Which languages a reader has actually read stays recorded, honestly and
+ * separately, in `packages/app/src/locales/REVIEW.md`.
+ *
+ * A stored preference naming a locale held out of this tuple still resolves
+ * normally — that is what lets a contributor run the app in the language they
+ * are checking.
*/
-export const PICKER_LOCALES = ['en', 'es', 'zh-Hans'] as const satisfies readonly SupportedLocale[];
+export const PICKER_LOCALES = [
+ 'en',
+ 'zh-Hans',
+ 'zh-Hant',
+ 'hi',
+ 'es',
+ 'fr',
+ 'bn',
+ 'pt-BR',
+ 'id',
+] as const satisfies readonly SupportedLocale[];
/**
* The locales whose chrome layout is not finished.
*
- * Both are right-to-left, and the chrome still lays out with physical margin,
- * padding and inset utilities rather than logical ones — so a right-to-left
- * base direction over it is visibly wrong rather than merely unpolished. Their
- * catalogs are complete and stay enumerated; what is unfinished is the layout
- * around the words.
+ * Both are right-to-left. Setting `dir="rtl"` does mirror the bulk of the
+ * chrome — the shell is flex and grid, which follow the writing mode on their
+ * own — so what is left is a set of specific defects rather than a wholesale
+ * retrofit, and `REVIEW.md` carries the measured inventory. They are enough to
+ * be worth holding for: text that reads left-aligned inside a right-to-left
+ * pane, `ml-auto` spacers that push to the near edge instead of the far one,
+ * arrows and disclosure chevrons that keep pointing the way they did, and
+ * `tracking-*` on section headings, which pulls Arabic letters apart at the
+ * joins and is the most visible of the lot.
+ *
+ * A green `pnpm check` is not evidence against this. The logical-property lint
+ * rule carries a documented pre-rule backlog — a file-level `biome-ignore-all`
+ * on the chrome files that predate it — and the shadcn primitives under
+ * `components/ui/` are exempt from it entirely.
*
* Reachable by an explicit stored preference and by the `OK_LANG` override, so
* a contributor can still run the app in the language they are checking. What
diff --git a/scripts/check-i18n-picker-completeness.test.mjs b/scripts/check-i18n-picker-completeness.test.mjs
index 2927807e6..5e9495243 100644
--- a/scripts/check-i18n-picker-completeness.test.mjs
+++ b/scripts/check-i18n-picker-completeness.test.mjs
@@ -18,8 +18,24 @@ const catalogOf = (entries) => new Map(Object.entries(entries));
describe('picker enumeration', () => {
const picker = readPickerLocales(readFileSync(LOCALES_TS, 'utf8'));
- test('reads the reviewed picker set out of core', () => {
- expect(picker).toEqual(['en', 'es', 'zh-Hans']);
+ // Membership belongs to `packages/core/src/i18n/locales.test.ts`, which pins
+ // it against the enumerated set. Restating it here would only mean two places
+ // to edit for one promotion, and a stale copy that fails on the wrong file.
+ test('reads the offered set out of core rather than restating it', () => {
+ expect(picker.length).toBeGreaterThan(0);
+ expect(picker).toContain('en');
+ expect(picker.filter((tag) => Intl.getCanonicalLocales(tag)[0] !== tag)).toEqual([]);
+ });
+
+ // The tuple is long enough that Biome wraps it one tag per line. A parse that
+ // only handled the single-line spelling would read it as empty and gate
+ // nothing, which is the one failure mode this reader cannot afford.
+ test('reads a tuple spread across lines, which is how core writes it', () => {
+ expect(
+ readPickerLocales(
+ ["export const PICKER_LOCALES = [", " 'en',", " 'zh-Hans',", '] as const;'].join('\n'),
+ ),
+ ).toEqual(['en', 'zh-Hans']);
});
test('refuses a source it cannot find the tuple in', () => {
diff --git a/scripts/generate-locale-review-packet.mjs b/scripts/generate-locale-review-packet.mjs
index 9d4c1bfae..e4a3b9a85 100644
--- a/scripts/generate-locale-review-packet.mjs
+++ b/scripts/generate-locale-review-packet.mjs
@@ -2,11 +2,12 @@
/**
* Build a self-contained review packet for one interface locale.
*
- * A locale enters the Settings picker when someone who reads it has reviewed
- * it. Nothing here decides that; this produces the artifact the reviewer reads.
- * The output is a single Markdown file with no links into a checkout, so the
- * reviewer needs a text editor and nothing else — no clone, no install, no
- * running app. `packages/app/src/locales/REVIEW.md` is the process around it.
+ * Most of the offered locales are machine-translated and unread. This produces
+ * the artifact that asks someone who reads one to fix that: a single Markdown
+ * file with no links into a checkout, so the reviewer needs a text editor and
+ * nothing else — no clone, no install, no running app.
+ * `packages/app/src/locales/REVIEW.md` is the process around it, and the record
+ * of which languages a reader has actually been through.
*
* The packet is a SAMPLE and says so. The catalogs hold ~2,900 messages per
* locale; nobody reads 2,900 strings as a favour, and a review request that
@@ -353,7 +354,7 @@ function endonym(locale) {
*/
function stakes({ offered, promotable }) {
if (offered) {
- return '- **If you approve:** nothing changes on screen — the language is already offered. What changes is that it is offered because someone read it, rather than because nobody had reason to doubt it. If you do not approve, we take it out of the picker.';
+ return '- **If you approve:** nothing changes on screen — the language is already offered. What changes is that it is offered because someone read it, rather than because nobody had reason to doubt it. Corrections are the expected answer and land as ordinary edits; if you tell us it is not usable as it stands, we take it out of the picker.';
}
if (promotable) {
return '- **If you approve:** the language is added to the in-app language picker and users can select it.';
@@ -577,8 +578,8 @@ function main(argv) {
if (!locale) {
console.error('Usage: node scripts/generate-locale-review-packet.mjs <locale> [--out <file>]');
console.error('');
- console.error(' Builds the review packet a native speaker reads before a locale can be');
- console.error(` offered in the language picker. Process: ${REVIEW_MD}`);
+ console.error(' Builds the packet a native speaker reads to tell us whether a locale');
+ console.error(` reads correctly. Process: ${REVIEW_MD}`);
return 1;
}
diff --git a/scripts/generate-locale-review-packet.test.mjs b/scripts/generate-locale-review-packet.test.mjs
index cadfd3c49..e6352d899 100644
--- a/scripts/generate-locale-review-packet.test.mjs
+++ b/scripts/generate-locale-review-packet.test.mjs
@@ -331,7 +331,7 @@ describe('the packet', () => {
expect(packetFor({ promotable: true })).not.toMatch(/will not appear in the picker yet/);
});
- // Two of the three offered locales have never been read. A packet that tells
+ // Eight of the nine offered locales have never been read. A packet that tells
// their reviewer they are deciding whether to ship a language that already
// shipped reads as a form letter, and gets treated as one.
test('does not tell a reviewer of an already-offered locale that it is unoffered', () => {
@@ -437,24 +437,29 @@ describe('the tracking table', () => {
expect(undefined_).toEqual([]);
});
- // The whole point of the record: nothing is offered on an unstated basis. Two
- // of the three current entries are `vouched` rather than `reviewed`, which is
- // the honest reading of how they got there.
- test('every locale the picker offers has its basis on the record', () => {
- const unaccounted = PICKER.filter(
- (locale) => !['source', 'reviewed', 'vouched'].includes(status.get(locale)?.status),
- );
- expect(unaccounted).toEqual([]);
- });
-
- test('every offered locale but the source states why it is offered', () => {
- const unexplained = PICKER.filter((locale) => locale !== 'en').filter((locale) => {
- const evidence = status.get(locale)?.evidence;
- return !evidence || evidence === '—';
+ // The reversal, stated as an invariant: an unread catalog is still offered,
+ // so the only thing that keeps an enumerated locale out of the picker is a
+ // recorded blocker. Withholding one for any other reason has to show up here
+ // as a failure rather than as a quiet omission from the tuple.
+ test('nothing is withheld from the picker without a recorded blocker', () => {
+ const withheld = SUPPORTED.filter((locale) => !PICKER.includes(locale));
+ const unexplained = withheld.filter((locale) => {
+ const blocker = status.get(locale)?.blocker;
+ return !blocker || blocker === '—';
});
expect(unexplained).toEqual([]);
});
+ // The other half of honesty: being offered claims nothing, but claiming to
+ // have been read claims something a stranger has to be able to check.
+ test('every locale recorded as read says who read it and where to look', () => {
+ const unsubstantiated = [...status.entries()]
+ .filter(([, row]) => ['reviewed', 'vouched'].includes(row.status))
+ .filter(([, row]) => !row.basis || row.basis === '—' || !row.evidence || row.evidence === '—')
+ .map(([locale]) => locale);
+ expect(unsubstantiated).toEqual([]);
+ });
+
// `vouched` records how the v1 picker got its entries. It is not a status to
// hand out — a locale outside the picker has no v1 grandfathering to record.
test('nothing outside the picker is marked vouched', () => {