菜单
The locale/i18n architecture of bagofwords — catalogs, resolution order, RTL, backend contracts — and the procedures for adding strings, adding a locale, or translating UI. Use when adding/changing user-facing strings, working on RTL, emails, localized errors, or anything locale-related.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/bagofwords1/bagofwords --skill localization命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
基于 SOC 职业分类
| name | localization |
| description | The locale/i18n architecture of bagofwords — catalogs, resolution order, RTL, backend contracts — and the procedures for adding strings, adding a locale, or translating UI. Use when adding/changing user-facing strings, working on RTL, emails, localized errors, or anything locale-related. |
Authoritative deep-dive: docs/design/i18n.md. This skill is the working map.
Catalogs live at the repo root: locales/{en,es,he,fr,sv,ar,ru,de,pt,it}.json
(10 locales). en is the authoritative catalog — its key set and ordering
define the shape; the target is identical key structure in every catalog.
es and he are the actively maintained translations; the other seven are
known to lag behind en (run the sync check below to see current drift).
he is the RTL reference — anything RTL must work for Hebrew; ar is also
RTL (plugin whitelists he/ar/fa/ur).
Hebrew vocabulary conventions: "הנחיות" (never "הוראות"), "גלריה" (never "לוח מחוונים"), "בדיקות איכות" (never "הערכות").
X-Locale request header — test-only override; must be in enabled_locales.localStorage["bow.locale"] on the client.OrganizationSettings.config["locale"], set via
/settings/general, served by GET/PUT /api/organization/locale
(PUT gated by manage_settings).bow_config.i18n.default_locale (en).
Enabled set: settings.bow_config.i18n.enabled_locales
(backend/app/settings/bow_config.py).Frontend (vue-i18n@9, composition mode):
frontend/plugins/i18n.ts — creates the global instance, imports catalogs,
applies persisted bow.locale, exposes $setLocale, sets <html lang> and
<html dir>.frontend/layouts/default.vue — after session ready, fetches
GET /api/organization/locale and applies effective_locale only when no
personal override exists.frontend/composables/useErrorMessage.ts — maps backend error_code +
params to t('errors.<code>', params), falling back to server detail.ms-*, me-*, ps-*, pe-*,
start-*, end-* — never ml-*/pl-*/left-*). Global icon flips and
third-party overrides in frontend/assets/css/rtl.css; opt out per element
with rtl-no-flip. Never dir="auto" on empty contenteditable — bind
:dir to the active locale.Backend:
get_current_locale(request) (unauthed-safe, header→default),
get_org_locale(request, organization) (header→org→default),
_locale_from_org(organization) for services holding an org object.backend/app/errors/): raise AppError.*(ErrorCode.X, ...),
never bare HTTPException. New code = enum entry in app/errors/codes.py
+ a matching errors.<code> key in every locale catalog.app/services/email_renderer.py + email_strings.py, shared Jinja
templates in app/templates/emails/*.jinja2 honoring lang/dir. Keep
substitutions HTML-escaped — description in share.html.jinja2 is | safe.app/ai/prompt_language.py injects a "mirror the user's
language" directive for conversational agents only (planner/answer/judge/
reporter/suggest_instructions) — reply in the language of the user's latest
message, overriding tool/page/schema/instruction languages; org locale is the
ambiguous-message fallback. Always emitted, including the en default.
Code/artifact agents stay English so SQL, identifiers, and JSON fields never
get translated.GET /api/config/i18n.Adding a string: add the key to locales/en.json under the right
namespace, then add the same key path to all other catalogs in one pass.
Use named interpolation (t('key', { name })) — never concatenation; word
order varies by language. Locale-reactive label/option arrays in
<script setup> must be wrapped in computed(() => [...]).
Run the sync check before and after your change — the catalogs have known
pre-existing drift, so the rule is: your diff must not increase any
missing/extra count (and should reduce them where cheap):
python3 - <<'EOF'
import json, pathlib
def flatten(d, p=''):
out = set()
for k, v in d.items():
f = f'{p}.{k}' if p else k
out |= flatten(v, f) if isinstance(v, dict) else {f}
return out
cats = {f.stem: flatten(json.loads(f.read_text())) for f in pathlib.Path('locales').glob('*.json')}
en = cats.pop('en')
for loc, keys in sorted(cats.items()):
missing, extra = en - keys, keys - en
print(f'{loc}: missing={len(missing)} extra={len(extra)}')
for k in sorted(missing)[:10]: print(f' - {k}')
print(f'en: {len(en)} keys')
EOF
Adding a locale: create locales/<code>.json mirroring en.json's full
shape; add the code to enabled_locales in backend/app/settings/bow_config.py
and the import in frontend/plugins/i18n.ts; if RTL, add it to the plugin's
RTL whitelist; extend frontend/tests/i18n/locale-sweep.spec.ts.
Testing: cd frontend && npx playwright test --config=playwright.i18n.config.ts
runs the locale sweep (asserts html[lang]/html[dir] flip, strings render,
no {{…}}/unresolved key paths leak, no [intlify] console warnings). Keep it
green for any catalog or locale change. For RTL-visible changes, capture a
Hebrew screenshot per the ui-evidence skill.
en.json only → sync check fails for the other 9 catalogs.confirm()/script-side strings — every
user-facing string comes from the catalog.Intl.* with locale.value.