diff --git a/.changeset/objectui-i18n-guide-locale-tags.md b/.changeset/objectui-i18n-guide-locale-tags.md
new file mode 100644
index 00000000000..52bab4b176a
--- /dev/null
+++ b/.changeset/objectui-i18n-guide-locale-tags.md
@@ -0,0 +1,8 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): the objectui i18n guide teaches the platform locale table's tags (`zh-Hans`, `zh-Hant`, `pt-BR`) for the built-in packs, a language switcher fed by `PLATFORM_LOCALES`, and the read aliases that keep a stored `zh` / `zh-CN` / `zh-TW` / `pt` resolving
+
+Clause-②: no
+Metadata-protocol: none
diff --git a/skills/objectui/guides/i18n.md b/skills/objectui/guides/i18n.md
index 00e282ddf45..19deafa2f32 100644
--- a/skills/objectui/guides/i18n.md
+++ b/skills/objectui/guides/i18n.md
@@ -1,7 +1,5 @@
 # ObjectUI Internationalization (i18n)
 
-Multi-language support via `@object-ui/i18n`.
-
 ## Setup
 
 ```typescript
@@ -10,10 +8,10 @@ import { I18nProvider, createI18n } from '@object-ui/i18n';
 const i18n = createI18n({
   defaultLanguage: 'en',
   fallbackLanguage: 'en',
-  detectBrowserLanguage: true,  // Auto-detect from navigator
+  detectBrowserLanguage: true,
   resources: {
     en: { common: { save: 'Save', cancel: 'Cancel' } },
-    zh: { common: { save: '保存', cancel: '取消' } },
+    'zh-Hans': { common: { save: '保存', cancel: '取消' } },
   },
 });
 
@@ -28,16 +26,18 @@ function App() {
 
 ## Built-in locales
 
-The package includes translations for:
-- English (`en`), Chinese (`zh`), Japanese (`ja`), Korean (`ko`)
-- German (`de`), French (`fr`), Spanish (`es`), Portuguese (`pt`)
-- Russian (`ru`), Arabic (`ar`)
+One pack per row of the platform locale table (`PLATFORM_LOCALES`, `@objectstack/spec/system`),
+keyed by tag: `en`, `zh-Hans`, `zh-Hant`, `es`, `ar`, `fr`, `pt-BR`, `ru`, `de`, `ja`, `ko`
+(`@object-ui/i18n/locales/<tag>`). No `zh` or `pt` pack: a stored `zh` / `zh-CN` resolves
+to `zh-Hans`, `zh-TW` to `zh-Hant` and `pt` to `pt-BR` via the table's read aliases
+(`resolveBuiltInLanguage`). Write the tag.
 
 ## useObjectTranslation hook
 
 <!-- os:check -->
 ```typescript
-import { useObjectTranslation } from '@object-ui/i18n';
+import { resolveBuiltInLanguage, useObjectTranslation } from '@object-ui/i18n';
+import { PLATFORM_LOCALES } from '@objectstack/spec/system';
 
 function Header() {
   const { t, language, changeLanguage, direction } = useObjectTranslation();
@@ -45,10 +45,10 @@ function Header() {
   return (
     <header dir={direction}>
       <h1>{t('common.appTitle')}</h1>
-      <select value={language} onChange={(e) => changeLanguage(e.target.value)}>
-        <option value="en">English</option>
-        <option value="zh">中文</option>
-        <option value="ar">العربية</option>
+      <select value={resolveBuiltInLanguage(language) ?? language} onChange={(e) => changeLanguage(e.target.value)}>
+        {PLATFORM_LOCALES.map(({ tag, label }) => (
+          <option key={tag} value={tag}>{label}</option>
+        ))}
       </select>
     </header>
   );
@@ -75,11 +75,6 @@ For large apps, load translations on demand instead of bundling all locales:
 
 RTL is automatic for Arabic, Hebrew, and other RTL languages. The provider updates `document.dir` when the language changes.
 
-```typescript
-const { direction } = useObjectTranslation();
-// direction: 'ltr' | 'rtl'
-```
-
 For Tailwind layout adjustments, use RTL-aware utilities:
 
 ```html
@@ -153,8 +148,6 @@ that travels without a bundle carries its own languages.
 
 ## Language-aware + responsive page
 
-When combining with `@object-ui/mobile` for responsive layouts:
-
 ```typescript
 import { I18nProvider } from '@object-ui/i18n';
 import { useBreakpoint } from '@object-ui/mobile';
@@ -176,7 +169,6 @@ function App() {
 
 ## Common mistakes
 
-- Bundling all locale files upfront — use lazy loading for apps with many languages.
 - Forgetting `dir={direction}` on root elements — RTL layout won't apply.
 - Using `{key, defaultValue}` translation objects — that key-reference vocabulary was retired.
   `@objectstack/spec` rejects the object with its own message: *an inline