i18n — localization (content table (A) / metadata table (B))

Audience: people building a tool (an XBundle package), and the AI working on their behalf. Both read the same document.

What it is

A package holds two kinds of translatable string, and they are written completely differently. Mixing them up raises no error — it just silently does nothing:

• Content table (A) — the text you write yourself, on widgets and pages, including finished sentences assembled in a data flow. It lives in one i18n table at the top level of the file and is referenced from the body with ${@i18n.key}.
• Metadata table (B) — the text the platform reads and displays itself: package name, package summary, widget title, route title. The bare field is the base language, translations hang off the same object under i18n, and nothing in the body references them.

The judgement in one line:

Any field the host reads and displays directly belongs in the metadata table (B); anything the package's own content resolves through the evaluator belongs in the content table (A).

A package runs fine without localization — but publishing is blocked: the storefront copy (name / summary) must exist in both Chinese and English.

Content table (A) vs metadata table (B)

The two tables treat the empty string in opposite ways, and that is deliberate. In the content table it is perfectly normal for zh-CN to say "天" while en-US says "" (English does not want that unit suffix); treating it as missing would render "Day 3天". An empty title in the metadata table, on the other hand, has never meant anything but an omission.

.xjob (reminders and background jobs) is the exception inside the metadata table: its message has this run's data substituted in, so a translation may write ${} directly, and its set of references must match the base language exactly (G47); the form slot can also override input hint text and option text. The full recipe is step 5 of numable docs alerts.

Language resolution: the fallback chain

Ask for a locale and it is tried first; then English; only then the author's own locale:

locale → other locales in the same language subtag (sorted by name) → en-US → manifest.lang (default zh-CN) → zh-CN → the remaining locales in the table

• Only locales that actually exist in the table are considered; spellings such as zh-Hans-CN and zh-CN are normalized before matching.
• The content table layers this chain per key: one missing line in one locale fills in just that line, and the table as a whole never drops to another language.
• The metadata table treats the bare field as the manifest.lang locale, then walks the first four segments of the same chain (exact → other locales in the same subtag → en-US → base language, without falling through to the remaining locales) and takes the first non-empty value.

manifest.lang is the base language, defaulting to zh-CN. It decides which locale every bare field belongs to, so getting it wrong tilts the fallback direction for the entire package.

The two language values

When the user explicitly picks Chinese or English the two are the same. They only diverge under "follow the system" when the system is neither Chinese nor English: the shell falls back to English while the content stays ja-JP — a package with a Japanese locale renders Japanese, one without it follows the chain above to English. So a package may support any locale, unconstrained by the shell's two.

Inside package content, always read the language as ${@app.language}.

Data flows: fetch by language, and produce text too

A .df may read ${@app.language} directly (as well as @device.language / @time.locale). For data the API itself serves per language (news headlines, city names, store descriptions), splice the language straight into the request:

{
  "id": "news",
  "action": "request",
  "params": {
    "url": "https://api.example.com/news?lang=${@app.language}",
    "formatType": "json"
  }
}

When the user switches language, the dashboard runs one widget.refresh per package (clear the fetch timer + a real fetch), so language-dependent data is updated. Switching language is rare, so refetching once is acceptable. Action flows (.af) may read the language too.

A .df has exactly the same shape as an .af: it may carry a top-level i18n table, the body writes ${@i18n.key}, and the flow's input carries the host page's table ⊕ this file's table (plus @app). To produce finished text in the data layer ("About the same as yesterday", "59% into today's range"), do it right in the .df:

{
  "version": 1,
  "actions": [
    { "id": "resp", "action": "request", "params": { "url": "https://api.example.com/today?lang=${@app.language}", "formatType": "json" } },
    { "op": "set", "props": { "key": "_b", "value": "1" } },
    { "op": "set", "props": { "key": "delta", "value": "${resp.delta}" } },
    { "op": "set", "props": { "key": "summary", "value": "$[if::(gt::(${delta},0),${@i18n.up},${@i18n.flat})]" } },
    { "action": "resultFilter", "params": { "keys": ["delta", "summary"] } }
  ],
  "i18n": {
    "zh-CN": { "up": "比昨天高", "flat": "和昨天差不多" },
    "en-US": { "up": "Higher than yesterday", "flat": "About the same as yesterday" }
  }
}

In one sentence: any flow file may have a top-level i18n table; write text as ${@i18n.key} and branch on language with ${@app.language}. Whether a plain word like "today" lives in the data layer or the rendering layer is your call. check applies the same G8 checks to a .df table as to an .af.

Two things to know:

• The data-cache key includes the language. After a switch, no widget has stored data for the new language yet: a skeleton shows first, then the data once fetched; switching language offline leaves no data to show for that language (the empty or error state appears). That is a deliberate trade-off.
• The theme (light/dark) is different from the language: it is a pure render parameter, switching theme only re-renders and never fetches, and the data cache is not split by theme either; colors rely on light|dark pairs.

Which layer a content table (A) applies to (scope merging)

The corollary: text drawn on widgets and pages is safest living in each .rcn's rc.i18n; finished sentences assembled in the data layer live in the .df's own table.

Content table (A) specifics

• Two flat levels: { "zh-CN": { "title": "…" }, "en-US": { "title": "…" } }. Do not wrap it in a values layer (check rejects it).
• Keys use [A-Za-z0-9_] only, and values must be strings.
• Keys cannot be built dynamically: ${@i18n.k_${n}} resolves to nothing. An unresolved reference is kept as its literal string in RCN / XPage, so ${@i18n.xxx} appears on screen.
• Interpolate by splitting into several keys rather than putting a placeholder in the translation and substituting it yourself: "${@i18n.pre}${n}${@i18n.post}".
• Plurals go in key_one / key_other, picked in the body with $[if::(…)].
• A locale may be any valid BCP-47 tag; zh-CN and en-US are required locales (along with the manifest.lang one), while a missing key in any other locale only raises a notice.
• A deliberately empty translation gets a declaration alongside it so it is not read as an omission: in .rcn write rc.i18nEmptyOk, in every other file a top-level i18nEmptyOk, holding an array of keys.

A minimal bilingual example, block by block

manifest.json — metadata table (B)

{
  "lang": "zh-CN",                       // base language: every bare field below belongs to this locale
  "title": "GitHub 示例",
  "subtitle": "某个用户最近的公开动态",
  "category": "developer",               // an enum key; the platform ships its own wording, no translation needed
  "i18n": {
    "en-US": { "title": "GitHub Sample", "subtitle": "A user's recent public activity" }
  }
}

Only four fields are translatable: title / subtitle / category / description. Since category is an enum key, it needs no translation.

.xwidget — metadata table (B)

{
  "version": 2,
  "title": "个股",
  "sub": "价格 · 两个月形状",
  "i18n": { "en-US": { "title": "Stock", "sub": "Price and its 2-month shape" } },
  "layout": 22
}

Only two fields are recognized: title and sub.

router.json — metadata table (B), hanging off each route

{
  "routes": [
    { "path": "/", "entry": "html/home/index.html" },
    { "path": "/detail", "entry": "html/detail/index.html",
      "title": "个股详情",
      "i18n": { "en-US": { "title": "Stock detail" } } }
  ]
}

Do not put a word table at the top level of router.json, and do not write ${@i18n.key} inside title — route titles are not evaluated, so the title bar shows the raw template string, and check always reports it.

.rcn — content table (A)

{
  "rc": {
    "cells": [
      { "id": "t", "type": "txt", "text": "${@i18n.title}", "fontSize": "18pt",
        "textColor": "#1A1A1A|#FFFFFF", "x": "12pt", "y": "16pt", "w": "-1", "h": "-1" },
      { "id": "u", "type": "txt", "text": "${temp}${@i18n.deg_post}", "fontSize": "13pt",
        "textColor": "#6B7280|#9AA0A6", "x": "12pt", "y": "44pt", "w": "-1", "h": "-1" }
    ],
    "i18n": {
      "zh-CN": { "title": "全球速览", "deg_post": "度" },
      "en-US": { "title": "World Markets", "deg_post": "" }
    },
    "i18nEmptyOk": ["deg_post"]
  }
}

deg_post is deliberately empty in English (English does not carry that suffix), and i18nEmptyOk states so, keeping it from being read as an omission.

.xpage — content table (A) at the top level, text living in each .rcn

{
  "type": "page",
  "id": "demo",
  "i18n": { "zh-CN": { "empty": "还没有数据" }, "en-US": { "empty": "Nothing yet" } },
  "root": { "…": "…" }
}

The page's table merges with the tables of the .rcn / .af files it references. Do not write ${@i18n.key} in a node's own properties — see the rules table.

.af — content table (A) at the top level

{
  "version": 1,
  "i18n": { "zh-CN": { "done": "已保存" }, "en-US": { "done": "Saved" } },
  "actions": [
    { "action": "ui.toast", "params": { "message": "${@i18n.done}", "type": "success" } }
  ]
}

A .df data flow's table has the same shape; see the example under "Data flows: fetch by language, and produce text too" above.

H5 pages — they carry their own table

The bridge offers no translation facility; an html page keeps its own word table and reads the language from data-lang:

<script>
  const T = {
    "zh-CN": { title: "我的记录", empty: "还没有记录" },
    "en-US": { title: "My log",  empty: "Nothing yet" }
  };
  const pick = () => T[document.documentElement.dataset.lang] || T["en-US"];
  function render() {
    document.getElementById("h").textContent = pick().title;
  }
  addEventListener("languagechange", render);   // switching the language dispatches an event, it does not reload the page
  render();
</script>

You can also read info.data.language via const info = await xbridge.appInfo(); (it must be awaited; the bridge returns an envelope with the result in data). See numable docs bridge.

Rules (breaking one means rework)

When something goes wrong

Related

• numable docs layout — every field of manifest.json, including the base language lang
• numable docs page — router.json's fields and the three page kinds
• numable docs rcn — how to write ${@i18n.key} and light|dark color pairs in a .rcn