国际化

概述

Immich 的国际化系统由两个主要组件组成：

语言系统：控制 UI 文本元素的翻译
区域设置系统：处理日期、数字和其他区域设置敏感内容的格式化

这些系统协同工作，提供完整的本地化体验，同时保持独立性以实现最大灵活性。

来源：web/src/lib/constants.ts267-352), web/src/lib/stores/preferences.store.ts25-52), web/src/lib/utils/i18n.ts1-33)

语言配置

支持的语言

Immich 通过 constants.ts 中定义的 langs 数组支持多种语言。每个语言条目包含：

name：人类可读的语言名称
code：语言代码（例如，'en', 'fr'）
loader：动态导入相应翻译文件的函数

默认语言是英语（en），备用区域设置是美式英语（en-US）。

用户选择的语言存储在 lang 存储中，该存储在会话之间保持不变。

来源：web/src/lib/constants.ts117-120), web/src/lib/constants.ts267-352), web/src/lib/stores/preferences.store.ts46-52)

翻译文件

翻译文件是存储在 web/src/i18n/ 目录中的 JSON 文档。每种语言都有一个以其语言代码命名的翻译文件（例如，en.json, fr.json）。

每个翻译文件包含键值对，其中：

键是代码中使用的标识符
值是该语言的翻译字符串

来源：web/src/lib/constants.ts267-352), web/src/lib/i18n.spec.ts1-51)

翻译流程

在组件中使用翻译

组件使用 svelte-i18n 的 t 函数来访问翻译

对于带参数的翻译：

来源：web/src/lib/components/album-page/album-card.svelte9-49), web/src/lib/components/user-settings-page/app-settings.svelte18-106)

区域设置系统

区域设置 vs. 语言

语言：控制 UI 文本使用哪个翻译文件
区域设置：控制日期、数字和其他格式化内容的显示方式

Immich 允许用户：

选择 UI 文本的语言
使用浏览器的区域设置进行格式化或选择特定的区域设置

所选区域设置存储在 locale 存储中

当 locale 为 undefined 时，使用浏览器的默认区域设置。

来源：web/src/lib/stores/preferences.store.ts39-44), web/src/lib/components/user-settings-page/app-settings.svelte39-90)

区域设置特定格式

区域设置特定格式使用 JavaScript 的 toLocaleString() 方法与所选区域设置结合使用

来源：web/src/lib/components/user-settings-page/app-settings.svelte74-89)

语言和区域设置选择的用户界面

用户可以在“应用程序设置”页面配置语言和区域设置。该界面提供：

一个包含所有支持语言的语言选择器下拉菜单
一个选项，用于使用浏览器的默认区域设置或选择自定义区域设置
所选区域设置的日期/时间格式预览

来源：web/src/lib/components/user-settings-page/app-settings.svelte1-177), web/src/lib/components/user-settings-page/user-settings-list.svelte50-58)

自动语言检测

当用户首次访问 Immich 时，应用程序会尝试检测其首选语言：

检查浏览器的 navigator.languages 数组
getPreferredLocale() 函数在支持的语言中找到最接近的匹配项
如果找到匹配项，则将其用作初始语言设置
如果未找到匹配项，则使用默认语言（英语）

来源：web/src/lib/utils/i18n.ts31-33), web/src/lib/stores/preferences.store.ts46-47)

开发者指南

添加新语言

要向 Immich 添加新语言：

在 web/src/i18n/ 目录中创建新的翻译文件（例如，xx.json）
在 constants.ts 的 langs 数组中添加一个条目

确保新文件中包含英文翻译文件中的所有键

来源：web/src/lib/constants.ts267-352), web/src/lib/i18n.spec.ts1-51)

测试翻译

i18n 系统在 i18n.spec.ts 中包含测试，用于验证：

所有语言文件在 langs 数组中都有相应的加载器
加载器正确导入预期的翻译文件
getClosestAvailableLocale 函数工作正常

来源：web/src/lib/i18n.spec.ts1-51)

最佳实践

始终对 UI 文本使用 t 函数：不要在组件中硬编码字符串
对动态内容使用参数：$t('key', { values: { param: value } })
使用不同语言进行测试：特别是从右到左书写的语言和非拉丁文字
保持翻译键的组织性：使用命名空间或前缀来组织相关键
为译者提供语境：使用清晰、描述性的键来表明语境

结论

Immich 的国际化系统提供了一种灵活而强大的方式来支持多种语言和区域设置。语言和区域设置的分离允许用户独立于其格式偏好选择其首选的 UI 语言。

通过遵循本文档中的指南，开发人员可以确保其组件得到适当的国际化，并贡献新的语言以使 Immich 能够被更广泛的受众使用。

国际化

概述