@byline/i18n (英语)
Byline CMS 的管理界面 i18n 原始文件 — 一个翻译注册, 一个 ICU Message Format formatter, 一个 React 提供者 + useTranslation() 钩子,自成一体 <LanguageMenu>,和纯本地分辨率级联.
这个包是 接口 i18n 的轴(管理员UI的语句)。 这个 内容 轴(文档以何种语言发布)是一个单独的关切问题,由 i18n.content 关于现有 BaseConfig两者是有意独立的.
完整的设计——注册模式、插件可扩展性表面、每个用户的持久性、未来阶段——见 docs/08-internationalization/index.md 在雷波根.
安装
pnpm add @byline/i18n
软件包将每个官方的 Byline 管理员翻译作为 JSON 文件捆绑在下面 src/admin/今天是英语en.json)和法语(fr.json; 添加新地块是单文件的PR. 这个 adminTranslations({ locales }) 工厂只读取所要求的代码,并组装一个捆绑.
三个入境点
import { mergeTranslations, createFormatter, resolveAdminLocale } from '@byline/i18n'
import { I18nProvider, useTranslation, LanguageMenu } from '@byline/i18n/react'
import { adminTranslations, en } from '@byline/i18n/admin'
- 根号 ——类型,事由,合并帮助器,地产级联. react-free; 服务器上的安全性 .
/react——提供方,钩子,开关. 按设计单管( 边接 Vite)optimizeDeps之前咬过这个代码库的背景识别陷阱 ./admin- 捆绑的byline-admin名称空间和adminTranslations(...)工厂.
最小接线
// apps/your-app/byline/admin.config.ts
import { defineAdminConfig } from '@byline/core'
import { adminTranslations } from '@byline/i18n/admin'
defineAdminConfig({
i18n: {
admin: {
defaultLocale: 'en',
locales: ['en'],
},
// … content locales as before
translations: adminTranslations({ locales: ['en'] }),
},
// … the rest of your admin config
})
添加第二个地块
import { adminTranslations } from '@byline/i18n/admin'
i18n: {
admin: { defaultLocale: 'en', locales: ['en', 'fr'] },
translations: adminTranslations({ locales: ['en', 'fr'] }),
}
捆绑的地块集导出为 bundledLocales 对于想要从可用内容中获取本地地址列表的主机:
import { adminTranslations, bundledLocales } from '@byline/i18n/admin'
i18n: {
admin: { defaultLocale: 'en', locales: [...bundledLocales] },
translations: adminTranslations({ locales: bundledLocales }),
}
adminTranslations({ locales: ['xx'] }) 当请求的代码不在时, 在配置时抛出 bundledLocales。要提供新语言,请将 JSON 文件与 src/admin/en.json 并将其添加到捆绑地图中.
插件贡献
一个插件(richtext扩展名,自定义字段,AI工具,.)将自己的JSON文件装入自己的包并曝光工厂匹配 adminTranslations形状——取出 { locales },返回 a TranslationBundle 用于插件本身的命名空间。 主机将它们合并到 defineAdminConfig数字 :
import { mergeTranslations } from '@byline/i18n'
import { adminTranslations } from '@byline/i18n/admin'
import { aiTranslations } from '@byline/ai/i18n'
i18n: {
admin: { defaultLocale: 'en', locales: ['en', 'fr'] },
translations: mergeTranslations(
adminTranslations({ locales: ['en', 'fr'] }),
aiTranslations({ locales: ['en', 'fr'] }),
),
}
载运主机未启用的地块的插件是无害的 —— 插件的厂家仅仅不返回代码, 合并后产生一个空条目, 启动验证器门对面 i18n.admin.locales 无论如何.
mergeTranslations 是关联性+决定性; 后期源在 (locale, namespace, key) 谷物和一 MergeOptions.onCollision 用于在开发过程中的表面冲突.
公约:
byline-admin——内置管理员外壳命名空间.byline-<package>- 每一个旁线包件(byline-richtext-lexical, (中文(简体) ),byline-ai(中文(简体) ).<org>-<plugin>——第三方插件(软件包名称为@财务报告和审定财务报表/平调.
使用 useTranslation 组件
import { useTranslation } from '@byline/i18n/react'
export function PublishButton() {
const { t } = useTranslation('byline-admin')
return <button>{t('common.actions.publish')}</button>
}
t(key, values) 总是返回字符串。 ICU MessageFormat语法在数值上工作——复数,日期,数字,选择:
t('list.unread', { count: 3 }) // "3 unread"
t('doc.publishedOn', { date: new Date() }) // "Published on May 28, 2026"
缺少的密钥掉入 active locale → default locale → raw key一发 console.warn 每个缺失 (locale, namespace, key) 三重火灾在德夫,所以差距是显而易见的.
服务器侧翻译
createFormatter 纯和无反作用,所以加载器和服务器函数直接使用:
import { createFormatter } from '@byline/i18n'
const { t } = createFormatter({
bundle, // the merged TranslationBundle
activeLocale: 'fr',
defaultLocale: 'en',
}).bind(null, 'byline-admin')
return { subject: t('email.invite.subject') }
在TanStack Start主机中, resolveServerTranslator(namespace) (以千美元计) @byline/host-tanstack-start)以请求解决的地块来包装.
地方分辨率级联
resolveAdminLocale 同样的纯级联运行在客户端和服务器上 所以SSR和水合产生相同的答案:
import { resolveAdminLocale } from '@byline/i18n'
const activeLocale = resolveAdminLocale({
locales: ['en', 'fr'],
defaultLocale: 'en',
preferred: actor?.admin_user?.preferred_locale,
cookie: getCookie('byline_admin_lng'),
acceptLanguage: getRequestHeader('accept-language'),
})
分级顺序 : preferred → cookie → acceptLanguage → defaultLocale。每个信号对允许的 locales 设置,所以一个 stale cookie 指向一个被移除的地盘 干净地掉下来.
这是什么 没有 这里( yet)
- 懒惰地装入. 当地人现在急切地捆绑着 超过 ~5 个本地位, 切换到 Async 加载器可赚取其复杂度; 见 阶段 3 in
docs/08-internationalization/index.md。 。 。 . - 撰写时间元数据 (按键描述,复数提示,去色标记). 第4阶段.
- RTL 管理员布局. 第5阶段:首先需要社区翻译的RTL locale来显示CSS破损的真实清单.
- 内置翻译编辑 (中文(简体) ). 蓄意出道.
许可证
MPL -2.0 (英语).