11. 翻译 - Phlo

11: 翻译

Phlo 使用 lang 资源来处理多语言视图文本和翻译。在视图中，您应该尽量使用紧凑的语言简写来编写静态文本。您可以使用自己的语言编写源文本；下面的示例使用荷兰语（nl）作为源语言。

11.1: 视图简写

在视图中静态可翻译文本的标准形式是：

view:
<p>{nl: Hallo wereld}</p>

在冒号之前的语言代码是文本的源语言。如果 %app->lang 与源语言相同，则文本按原样显示。如果活动语言不同，%lang 将使用翻译缓存并异步调度缺失的翻译。

简写仅适用于静态文本。冒号和闭合大括号之间的所有内容都变成一个单一的字符串参数：{nl: Hallo wereld} 转换为 {{ nl('Hallo wereld') }}，因此其中没有占位符或参数语法。

对于动态值，请在表达式中调用 nl() / en() 函数。这些函数接受 sprintf 风格的参数：

view($name):
<p>{{ nl('Hallo %s', $name) }}</p>

%s 生活在翻译后的源字符串中（因此缓存键保持稳定），参数在翻译后被替换。当需要插值时，使用静态文本的简写和函数。

11.2: 代码中的助手

当前的 lang 资源为荷兰语和英语提供全局辅助函数：

method title => nl('Welkom')
method intro => en('Build compact full-stack apps')

这些助手在方法、props 或控制器代码中非常有用。在 views 中，简写通常更清晰：

view:
<h1>{nl: Welkom}</h1>
<p>{en: Build compact full-stack apps}</p>

11.3: 主动语言

活动语言存储在 %app->lang 中。在视图渲染之前，路由可以设置它：

route both GET $lang:nl,en=nl guide {
	%app->lang = $lang
	view($this)
}

在链接中，您可以使用 %lang 作为对象值来显示或处理当前语言。

11.4: 翻译缓存

翻译是通过 %INI(%app->lang, langs) 从 langs/ 按语言加载的。缺失的条目会基于它们的哈希值异步翻译，并在稍后从缓存中读取。

核心方法包括：

%lang->translation('nl', 'Hallo wereld')
%lang->translate('nl', 'en', 'Hallo wereld')

使用 translation() 进行正常的应用渲染，同时支持缓存和异步回填。只有在您故意想要执行单个直接翻译时，才使用 translate()。

11.5: 翻译说明

lang 资源为 AI 翻译器提供数据，您可以对其进行引导。instructions 属性是翻译器在每次翻译时接收到的额外上下文：您的领域、术语以及关于哪些内容必须保持原样的规则。一个应用通过构建模块将其注入：

prop %lang.instructions = 'Documentation for the Phlo language. Keep keywords like route, view and prop in English. Keep common English technical terms (best practices, deployment, release) untranslated where that reads naturally, and prefer natural phrasing over forced, over-literal translation.'

没有指令，翻译器仅根据文本工作。使用它们可以保持专有名称和关键词不变，并避免对目标语言中已经常见的术语进行生硬的翻译。默认值是 void。相同的指令也适用于通过 docs 机制翻译的markdown文档，该机制读取 %lang->instructions。

11.6: Best practices

在 views 中使用 {nl: ...} 和 {en: ...} 来处理静态文本；对于带参数的内容使用 nl() / en()。
在 views 之外的 PHP/Phlo 代码中使用 nl() 和 en()。
早期设置 %app->lang，在 route 或中央控制器中。
保持源文本稳定；更改的文本会生成新的哈希值。
设置 %lang.instructions，以便翻译者保持您的术语并避免强制翻译。
仅记录实际存在的作为资源函数的语言助手。