JsonUI
← GuidesAdding a new languageOne strings.json feeds three different output shapes: a Swift StringManager struct, an Android strings.xml resource tree, and a reactive TypeScript StringManager singleton. There is no standalone `jui localize` command — it is all handled by `jui build`'s resource distribution step. This guide covers the real asymmetries between platforms and the five mechanical steps for adding a new locale.~12 min read
1. The bilingual shapestrings.json is a two-level JSON: the outer key is a screen namespace, the inner key is a snake_case string name, and the value is either a { en, ja, … } object or a plain string (used as fallback for every locale). The multi-language object form is what the generators look for — a plain string is a 'not yet translated' placeholder. A third form covers counted text: a plural entry, where each language holds { "plural": { "one": "{count} item", "other": "{count} items" } } with CLDR cardinal categories.
docs/screens/layouts/Resources/strings.json (excerpt)
{
"home": {
"hero_title": {
"en": "One spec. Native iOS, Android, and Web.",
"ja": "ひとつの仕様で、iOS・Android・Webを描く。"
},
"hero_cta_primary": {
"en": "Install in one line",
"ja": "ワンライナーで導入"
}
},
"cells_agent_row": {
"placeholder_response_empty": "Response will appear here."
}
}
2. How namespaces are namedNamespace names are derived automatically from the layout file path: slashes become underscores, hyphens become underscores. `home.json` → namespace `home`. `learn/hello-world.json` → `learn_hello_world`. `cells/agent_row.json` → `cells_agent_row`. Keys within a namespace are snake_case. `jui build` auto-extracts string literals from layout text / hint / placeholder / label / prompt properties and inserts them; you can also add keys by hand. A display text written as the exact text of a key in the layout's own section resolves to that key on all three faces. Measured here on web: a Label written as the literal text of its section's title rendered that key's lookup. Text that matches a key only in another section is not searched and stays a literal, and an empty text is never looked up. `jui lint-strings` is the gate on the other side of that: it fails when a user-visible string sits in a layout as a raw literal instead of resolving through strings.json. It can also check that the declared set and the referenced set agree, via `--usage` on a run or `lint.stringsUsage: true` in `jui.config.json` — opt-in, so the plain command and `jui build` do not run it. A reference from test code does not make a key used — a test that reads a key proves nothing about the app showing it — and the run says where it looked: on this site, `usage scanned 719 source file(s), excluded 0 as test code` and `test code (web): test runner defaults: *.test.*, *.spec.*, __tests__/`. Test code is where each platform's build declares it (iOS: the test targets in project.pbxproj; Android: the test source sets; web: the runners' default file names), and `lint.stringsUsageTestPaths` adds directories per platform. It reports three things: keys declared here that nothing references (wiring that was never finished, which every other gate passes), keys a caller asks for that are not declared (on web `getString` hands back the key name, so the raw key reaches the screen; Android's compiler already refuses a missing R.string symbol, so that face is not reported. iOS splits: StringManager accessors fail to compile too, but hand-written `NSLocalizedString(...)` / `String(localized:)` never do — Foundation returns the key string itself — so those two forms are checked against strings.json and the platform string catalogs (*.strings / *.xcstrings / *.stringsdict, actually read), and only a reference found in neither is reported, with file:line. The `"key".localized()` form is counted as usage but never reported missing: the SwiftUI generator emits that spelling for sentinel values too — a visibility's "gone", for instance — so an unresolved one is usually not a key reference at all, and reporting it would bury the real findings), and dynamic key selection that does not go through a declared map. Three conventions keep the referenced set computable: build dynamic key choices from a constant map named `*_STRING_KEYS`, so the possible values sit in the closure (prefer the object form — its values are checked against the declared set too; in an array of pairs the scanner cannot tell which element is the key, so those literals count as used but are never reported missing); pass a literal — or a choice among literals, `cond ? "a" : "b"` is fine — as the first argument of `str()` / `tpl()` / `getString()` / the qualified `StringManager.plural(key, count)`, while something like `MAP[x] ?? "lit"` counts as dynamic — only the first argument is judged, so parameter objects or a count in later arguments never make a call dynamic; and park keys you are deliberately holding for later in a `LINT_KEEP_STRING_KEYS` map. The check stays deliberately unclever — it does not guess at prefixes, because a dead key hiding under a guessed exclusion would never surface again (an unqualified `plural(` is ignored for the same reason: it could be anyone's helper). There is one place the literal rule stops being lenient, and a definition is what licenses it: when the same file defines `function str` or `function tpl` and the body is statically readable — ``getString(`prefix_${key}`)`` or `getString(key)` — the literals passed to it are checked as the composed key exactly, and a mismatch is reported as missing under that composed name. Measured on a fixture whose wrapper composes `home_` with its argument: `str('farewel')` is reported as composing `home_farewel`, which is not declared, while `str('greeting')` resolves. Moving that wrapper into another file and importing it is the only edit needed to turn the strictness back off — imported wrappers, unreadable bodies and contradictory definitions keep the broad matching, because the definition is what makes the composition knowable, and a guess would be worse than leniency. Accessors that are methods rather than free functions are untouched: this site's own are. The usage scan leaves out a file git ignores and does not track — `next-env.d.ts`, which `next dev` writes into a web face, for one — except a file that carries @generated near its top, which still counts, because generated code references keys. A face kept wholly outside git is scanned in full. Measured on this site with two planted files that git ignores: a plain one is not counted (`usage scanned 839`), and one marked @generated is.
namespace derivation
layout file → namespace
─────────────────────────────────────────────────
home.json → home
learn/hello-world.json → learn_hello_world
cells/agent_row.json → cells_agent_row
guides/localization.json → guides_localization
3. What each platform emitsBuild time produces three different files from the same source — this is the most frequently misunderstood part of JsonUI localisation. Do not assume Android has a StringManager.kt; it does not.• iOS: ResourceManager/StringManager.swift (nested struct, snake_case → camelCase functions) + Localizable.strings per locale. Access: StringManager.Home.heroTitle().• Android: res/values/strings.xml + res/values-ja/strings.xml (no StringManager.kt — kjui intentionally disables it, the native R.string API is used instead). Access: context.getString(R.string.home_hero_title). kjui writes its entries inside a `JsonUI generated strings (kjui): begin / end` region of strings.xml and prunes only inside it, so hand-written entries outside the region are left alone.• Web: src/generated/StringManager.ts (singleton with a camelCase proxy over the language tables). Access: StringManager.currentLanguage.homeHeroTitle.
StringManager.ts (excerpt)
// Web — src/generated/StringManager.ts (@generated)
const strings = {
en: { home_hero_title: "One spec. Native iOS, Android, and Web." },
ja: { home_hero_title: "ひとつの仕様で、iOS・Android・Webを描く。" },
};
// usage
$s.homeHeroTitle;
strings.xml (excerpt)
<!-- Android — res/values-ja/strings.xml (@generated) -->
<resources>
<string name="home_hero_title">ひとつの仕様で、iOS・Android・Webを描く。</string>
</resources>
4. Runtime language switchingReactive language switching is Web-only. `StringManager.setLanguage(locale)` mutates the singleton and React re-renders consuming components — the generated string hook subscribes through useSyncExternalStore, so this is React behavior, not a Next.js feature. On iOS and Android, StringManager has no setLanguage API — the device locale is the source of truth, picked up via Settings > General > Language on iOS and Settings > System > Languages on Android. In-app toggles on mobile require hand-written code (Locale.preferredLanguages on iOS, AppCompatDelegate.setApplicationLocales() on Android).
Web language toggle (hand-written)
"use client";
import { StringManager } from "@/generated/StringManager";
import { useRouter } from "next/navigation";
 
export function LanguageToggle() {
const router = useRouter();
return (
<button onClick={() => {
const next = StringManager.language === "ja" ? "en" : "ja";
StringManager.setLanguage(next);
router.refresh();
}}>
{StringManager.language === "ja" ? "EN" : "JA"}
</button>
);
}
5. Adding a new locale (five steps)All mechanical, no schema updates. Pick a BCP-47 code (fr, de, zh-Hans, ko, …) and:① Add the locale to each object in strings.json. Plain-string keys fall through to their existing value at runtime, so you only add the third key where translation actually exists. An object with no text for the new code shows another language's text; the build says so (below).
① strings.json
{
"home": {
"hero_title": {
"en": "One spec.",
"ja": "ひとつの仕様で。",
"ko": "하나의 사양."
}
}
}
② Name the output. Web: add the code to languages[] in rjui.config.json. iOS and Android: add the output's path to string_files in sjui.config.json and kjui.config.json, such as ko.lproj/Localizable.strings and res/values-ko/strings.xml. On iOS the path is read under source_directory. jui init writes Localizable.strings; an entry that names source_directory again, such as MyApp/Localizable.strings under source_directory MyApp, is read as written and not found, and the warning says what to write instead (measured with an empty .xcodeproj). languages[] in sjui.config.json, kjui.config.json or jui.config.json makes no output: measured, fr added to all three produced no fr.lproj and no values-fr.
② jui.config.json
// rjui.config.json (Web)
{ "languages": ["en", "ja", "ko"], "default_language": "en" }
 
// sjui.config.json (iOS): paths under source_directory
{ "string_files": ["Localizable.strings", "ja.lproj/Localizable.strings", "ko.lproj/Localizable.strings"] }
 
// kjui.config.json (Android)
{ "string_files": ["res/values/strings.xml", "res/values-ja/strings.xml", "res/values-ko/strings.xml"] }
③ Run jui build. Android creates res/values-ko/strings.xml. iOS writes only into a file that is already there: create an empty ko.lproj/Localizable.strings first, or the build prints WARNING: Strings file not found with the path it looked at, writes nothing for that language and still exits 0. Web's StringManager.ts gets a ko branch in its strings object.
③ shell
# iOS: the file must be there first, under source_directory
mkdir -p ko.lproj && touch ko.lproj/Localizable.strings
 
jui build
# → ko.lproj/Localizable.strings is filled for iOS
# → res/values-ko/strings.xml is created for Android
# → StringManager.ts gets a `ko` branch
④ iOS only: open Xcode → Project > Info > Localizations and add the language there once. Android and Web pick up the new files automatically, no IDE action needed.⑤ Web only: expose a language toggle that calls StringManager.setLanguage('ko'). On iOS and Android this would happen via OS-level language change; the app will refresh on next launch.Language tags with more than one wordKeys in strings.json such as zh-Hant, zh-TW, pt-BR and es-419 reach their output.• Folders: zh-Hant.lproj, zh-TW.lproj, pt-BR.lproj and es-419.lproj on iOS; values-b+zh+Hant, values-zh-rTW, values-pt-rBR and values-b+es+419 on Android. Not values-es-r419: jsonui-cli measured that aapt2 34, 35 and 37 refuse it. On the web the name is the languages[] entry.• Which text: the tag's own key first, then a shorter one, so pt-BR takes pt and es-419 takes es. With neither, the default language's text.• Chinese: zh-Hant and zh-TW stand in for each other and never take zh, because iOS and Android treat a plain zh as Simplified (jsonui-cli's measurement on iOS 26.2 and Android API 35). A key with only en and zh shows en on those two, with the warning below. zh-Hans and zh-CN stand in for each other and do take zh.• The warning: one line per output, for any language, one-word tags too, and the build still exits 0: zh-Hant.lproj: 4 key(s) have no zh-Hant text and show another language's: home_a, home_b, home_c, home_d. After 5 keys it adds and N more. Android names values-b+zh+Hant, and the web names languages[zh-Hant]. A key whose shorter form has text, such as pt for pt-BR, is not counted, and neither is a plain-string key (read from the code).Measured here: jui build on a three-platform scratch project with ten folders per mobile platform, reading the generated files. On this site's en and ja, the warnings are 0. Not measured here: a real Xcode or Gradle build with these folders, and any device. jsonui-cli has measured the language a device picks on iOS 26.2 and API 35 only, not API 24 to 34, not the plural form picked at run time, and not other scripts such as sr-Latn.The words on a SelectBox sheetThe sheet a SelectBox opens on iOS and Android has words of its own, and they come from the library, not from your strings.json. They follow the language the app shows its text in, in 15 languages: English, Japanese, Korean, German, French, Spanish, Latin American Spanish, Dutch, Danish, Polish, Czech, Portuguese (two kinds), and Simplified and Traditional Chinese. Any other language gets English. The web draws a native select, so it has no such words.• Android: the sheet's title, Cancel, a date sheet's confirm button, and the Year, Month, Day, Hour and Minute labels on the wheels. They follow the app's language (an English screen reads Select an option and Cancel). The language is the app's AppCompat application locales, then the context's. Two things do not follow it: the month names on the wheel (Jan to Dec, or 1月 to 12月 when dateStringFormat has 月), and the sheets of the XML mode, which keep their Japanese words.• iOS: the only fixed word is on the button that closes the sheet, list or date. If the app's Localizable.strings translates the key Done, that translation comes first. Without one, SwiftJsonUI uses the word UIKit uses: 完了 in Japanese, Fertig in German, and OK in French, among others.• To change a word on one SelectBox: sheetTitle and cancelButtonText on Android, doneButtonText on iOS and on an Android date sheet. Each takes a text, a strings.json key or a binding, read the way prompt is read.• To change a word in the whole app: on Android declare the same name in your own values (kjui_sheet_select_option, kjui_sheet_cancel, kjui_sheet_confirm, kjui_sheet_select, kjui_sheet_select_date, kjui_sheet_select_time, kjui_sheet_select_date_and_time, kjui_sheet_year, kjui_sheet_month, kjui_sheet_day, kjui_sheet_hour, kjui_sheet_minute). On iOS translate the key Done in Localizable.strings.• In a layout shared across platforms: sheetTitle and cancelButtonText print one WARNING per use on the iOS and web builds (is Kotlin only) and generate nothing there, and the build still exits 0. doneButtonText says nothing where it does nothing: on an Android list sheet, which has no confirm button, and on the web. A calendar date sheet on Android has one button and no cancel, so cancelButtonText changes nothing there.Measured here: jui build on a three-platform scratch project with a list, a strings.json key, a date and a binding, reading the generated code and the warnings; the words, the call order and the XML mode read from the KotlinJsonUI and SwiftJsonUI sources. A real Xcode or Gradle build and any screen are not measured here. jsonui-cli checked on a device only Cancel and キャンセル, changing the language by replacing the Activity, and iOS on 26.2 only; Android API 24 to 34, the device's own language setting, VoiceOver and the 15 languages word by word are not measured. Six words were written by jsonui-cli rather than taken from the system (Select an option, Select date and time, Select, Year, Month, Day), and a speaker's check of them is still asked for. If one reads wrong, replace it as above.
6. Limits and asymmetriesA few things JsonUI localisation does not do today — know them up front so you don't spend time looking for them.• Plurals: supported via CLDR-cardinal plural entries ({ "plural": { "one": …, "other": … } }, `{count}` placeholder). Each platform compiles to its native engine — .stringsdict (iOS), R.plurals (Android), Intl.PluralRules (web). Plural keys are VM-only: resolve them in the ViewModel (StringManager accessor with count / getQuantityString / StringManager.plural) and bind the result; referencing one from a layout attribute is a build error. A special count=0 wording stays a ViewModel branch, not a plural category. The separate-keys idiom (item_singular / items_plural) also works. Every language of the strings.json needs its own forms in a plural entry: a missing one is an ERROR on all three faces, naming the key, the missing languages and the language set. Measured on web: an entry with en forms and no ja fails. On iOS the category is picked in the app language the format came from, not the device locale.• Interpolation: iOS uses %@, Android uses %s — the build auto-converts between them, and positional specifiers (%1$@ / %1$s) are supported. Web strings stay literal for these specifiers (no printf engine); the only substitution the web runtime performs is `{count}` inside plural entries, resolved via Intl.PluralRules.• Pseudo-localisation: no tool for auto-wrapping keys with brackets to surface missing translations. jui build names them instead: one WARNING line per output, with the count and the first 5 keys (below in section 5).• Images: `alt` text IS localizable — a registered strings.json key in `alt` resolves through StringManager just like `text` / `hint` (measured on web: `alt={$s.homeHeroTitle}`). An image with no `alt` is decorative: on web it renders `alt=""`, exactly as `"alt": ""` does. iOS and Android read `alt` too — VoiceOver and TalkBack speak it, `accessibilityLabel` and `contentDescription` are accepted as its spellings, and it takes a binding — and treat a missing one as decorative as well, except on an image that operates a control, which is read by its id or asset name and is named by the build. That native half is the declaration's and is not measured here; on web the same tappable image kept `alt=""` and the build named nothing. So give every image that carries meaning an alt. Image sources are NOT localizable: `src` / `url` literals never go through the string table — registering an image name as a string key is the classic way to break a picture — and a bare-name `src` triggers a build warning telling you to use `srcName` instead.
Keep reading
Writing your first specStrings are part of the spec contract./guides/writing-your-first-spec
Data binding as contractHow text bindings flow through StringManager./concepts/data-binding