语言区域与文本方向
利用运行时的语言区域元数据,为文档和本地化子树设置语言与方向。
翻译后的文本应与文档方向保持一致。提供阿拉伯语消息目录会改变消息内容,但浏览器还需要 dir="rtl",才能按预期的阅读方向布局页面。提供器和文档属性应使用同一个解析后的语言区域。
同时设置语言与方向 #
在框架的文档组件或外壳组件中,根据当前请求选定的语言区域生成属性:
import type { ReactNode } from "react";
import { createLingo, LingoProvider, type Messages } from "@lingo.dev/react";
export function LocalizedDocument({ locale, messages, children }: {
locale: string;
messages: Messages;
children: ReactNode;
}) {
const l = createLingo(locale);
return (
<html lang={l.locale} dir={l.direction}>
<body>
<LingoProvider locale={locale} messages={messages}>
{children}
</LingoProvider>
</body>
</html>
);
}使用此模式时,请保留框架所需的头部、脚本和水合组件。如果本地化子树位于另一种语言的页面中,则应根据该子树的 useLingo() 结果,在其容器元素上设置 lang 和 dir。局部区段的属性不能替代整个文档的语言设置。
尽可能在初始 HTML 中设置这些属性。如果等到水合后才更新方向,页面可能会先显示错误的布局。
准确解读元数据 #
| 成员 | 含义 |
|---|---|
locale: string | 输入的语言区域,原样保留。 |
direction: "ltr" | "rtl" | 优先采用原生 Intl.Locale.textInfo 提供的方向;不可用时,采用运行时基于语言的回退方向。 |
script: string | undefined | 使用 Intl.Locale 补全语言区域后推断出的文字系统。 |
region: string | undefined | 通过同一次补全推断出的地区。 |
例如,createLingo("en") 可以推断出 Latn 和 US。这只是补全可能的语言区域子标签,并不会定位读者或确定账单所属国家。如果应用需要这些信息,请使用实际的账户或位置数据。
如果 Intl.Locale 不可用或标签无效,文字系统和地区可能未定义,方向则根据回退语言列表确定。其他原生格式化器仍可能拒绝无效标签。渲染前,请根据应用支持的语言区域集合解析语言区域。
让布局遵循阅读方向 #
使用 margin-inline-start 和 padding-inline-end 等 CSS 逻辑属性,让间距随文本方向调整。请逐一检查图标:导航箭头可能需要反向,实物图像则未必需要。语言区域元数据提供方向,组件设计决定这一方向如何影响界面。
提供器不会协商语言,也不会获取消息。Locale-router 提供 URL 和偏好策略。Next Pages 包装器 会同步方向,但文档的 lang 仍由应用设置;TanStack 外壳 则根据请求上下文同时设置两者。
切换语言后,请一并检查文档属性和已加载的消息目录。服务端渲染说明了为什么水合阶段也必须接收到相同的语言区域、消息和格式化输入。