多语言集成和真相来源

PolyCMS 提供强大的、全球可用的翻译架构，可自动发现并合并来自核心、模块和主题的本地化文件。

为了确保性能而不牺牲管理员的易用性，系统使用编译管道架构。作为开发人员，了解 真相来源 的概念对于防止数据丢失或静默翻译失败至关重要。

1. 编译管道架构

PolyCMS 将翻译存储分为两种格式：

.json 文件（事实来源）： 这些是人类可读、管理员可编辑的字典文件。

.php 文件（编译缓存）： 这些是系统生成的高性能 PHP 数组。

它在运行时是如何工作的

当页面加载（后端或前端）并且字符串需要翻译时，核心“LanguageHelper”仅从编译的“.php”缓存文件中读取。它不会在运行时扫描或解析“.json”文件以保证最大渲染速度。

编辑期间如何工作

当管理员通过 PolyCMS 管理 UI（设置 > 语言）编辑语言时，系统会读取并写入“.json”文件。保存后，系统自动触发编译器重新生成.php缓存。

2. 开发人员工作流程：添加翻译

开发模块或主题时，您经常需要添加新的可翻译字符串。

文件位置

翻译应放置在扩展根目录的“lang/”目录中：

模块： modules/Vendor/ModuleName/lang/{locale}.json

主题： themes/theme-slug/lang/{locale}.json

黄金法则

关键：“{locale}.json”文件是绝对的真相来源。您绝不能手动编辑“{locale}.php”文件，因为系统编译器将覆盖它。

分步翻译工作流程

添加到 JSON： 打开模块或主题的 lang/en.json 或 lang/vi.json 并添加新的键值对。

{
    "My Custom Setting": "Cài đặt tùy chỉnh của tôi",
    "Show Blog Header": "Hiển thị Header Blog"
}

编译为 PHP： 因为系统仅从 .php 读取，所以您的新 JSON 键只有在编译后才会生效。您必须在开发环境中手动触发编译器。

使用 Artisan Tinker：

php artisan tinker --execute="app(\App\Services\LanguageService::class)->compileToPhp('vi');"

或者，您可以转到 PolyCMS 管理面板：设置 > 语言，然后单击 编译 按钮。

验证： 硬重新加载（Ctrl + F5）您的浏览器。新的翻译现在应该出现在用户界面中。

3. 格式化警告和静默失败

如果您运行编译命令但翻译仍然没有出现，这几乎总是由于 JSON 文件无效。

如果“json_decode()”无法解析您的“.json”文件，“LanguageService”将默默地跳过它以防止应用程序崩溃。

要避免的常见 JSON 格式错误：

UTF-8 BOM： 确保您的代码编辑器（或 PowerShell 的“Set-Content”等终端命令）不会注入字节顺序标记 (BOM)。该文件必须是纯“UTF-8”。

尾随逗号： JSON 不允许在最后一项后使用尾随逗号。

未转义的引号： 确保字符串中的所有双引号均已正确转义（例如，\"）。

4. 在代码中使用翻译

编译后，您可以在模块或主题的不同层无缝地使用翻译字符串。

在刀片模板中

始终在 Laravel 的本机翻译器 __() 或 PolyCMS 帮助器 _l() 中包装硬编码文本：

<button>{{ __('Show Blog Header') }}</button>

在 PHP 中（控制器、服务提供者）

使用“_l()”帮助器来管理字符串、菜单标签或设置：

$menuRegistry->addChild('content', [
    'key' => 'blog_enhancer_tools',
    'label' => _l('SEO Tools'), // Translates automatically based on Admin's language
    'url' => '/admin/blog-enhancer'
]);

在 Vue 组件中

导入并使用全局 useTranslation 可组合项：

import { useTranslation } from '@/admin/composables/useTranslation';

const { t } = useTranslation();

// In your Vue template:
// <h2>{{ t('SEO Tools') }}</h2>