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，以便翻译者保持您的术语并避免强制翻译。
仅记录实际存在的作为资源函数的语言助手。