在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

go-gitea/gitea

菜单

配置和国际化

相关源文件

本文档介绍了 Gitea 的配置系统和国际化框架。这两个核心组件使管理员能够自定义 Gitea 的行为并支持多种语言的用户。

有关数据库配置的具体信息，请参阅数据库系统。

配置系统概述

Gitea 使用一个灵活的配置系统，主要基于名为 app.ini 的 INI 格式文件，并通过环境变量和命令行标志支持覆盖。

来源：modules/setting/setting.go21-57 custom/conf/app.example.ini1-366

配置源层次结构

Gitea 启动时，它会按以下优先级顺序加载配置

  1. 命令行标志
  2. 环境变量
  3. 配置文件（app.ini）
  4. 应用程序中硬编码的默认值

这种层次结构允许灵活的部署策略，从开发到容器化的生产环境。

配置路径

配置系统在启动时确定几个重要路径

路径变量描述确定方法
AppPathGitea 可执行文件路径运行的 gitea 二进制文件的绝对路径
AppWorkPath工作目录app.ini 中的 WORK_PATH、--work-path 标志、$GITEA_WORK_DIR 环境变量或编译时值
CustomPath自定义文件目录--custom-path 标志、$GITEA_CUSTOM 环境变量或 AppWorkPath/custom
CustomConf配置文件路径--config 标志、编译时值或 CustomPath/conf/app.ini

来源：modules/setting/setting.go36-45 cmd/web.go1-20 custom/conf/app.example.ini14-37

配置文件结构

app.ini 文件按相关配置选项的组织方式分为几个部分

主要配置部分包括

  • [server] - Web 服务器设置（协议、域名、端口、URL）
  • [database] - 数据库连接参数
  • [repository] - 存储库处理配置
  • [security] - 安全相关设置
  • [service] - 服务相关选项
  • [oauth2] - OAuth2 身份验证设置

来源：custom/conf/app.example.ini40-366

环境变量

app.ini 中的配置可以通过环境变量覆盖，使用此模式

GITEA__SECTION_NAME__KEY_NAME=value

例如，要覆盖 [server] 部分的 ROOT_URL

GITEA__SERVER__ROOT_URL=https://git.example.com/

此功能对于容器化部署或使用 Kubernetes 等编排工具特别有用。

来源：custom/conf/app.example.ini362-365

配置代码结构

配置系统在 modules/setting 包中实现，并为不同的子系统提供了专门的文件

  • setting.go - 核心设置和初始化
  • repository.go - 存储库特定设置
  • service.go - 服务相关设置
  • lfs.go - Git LFS 设置
  • oauth2.go - OAuth2 设置
  • security.go - 安全相关设置
  • attachment.go - 附件设置
  • actions.go - GitHub Actions 类似的 CI/CD 设置

来源：modules/setting/setting.go1-57 modules/setting/repository.go1-20 modules/setting/service.go1-20 modules/setting/lfs.go1-13 modules/setting/oauth2.go1-10

配置加载过程

来源：modules/setting/setting.go36-45 cmd/web.go1-20

配置结构和访问

来源：modules/setting/config_provider.go1-10 custom/conf/app.example.ini40-366

国际化系统

Gitea 的国际化 (i18n) 系统能够以多种语言显示用户界面。它使用本地化文件存储翻译，并根据用户偏好自动选择合适的语言。

来源：options/locale/locale_pt-PT.ini1-100

支持的语言

Gitea 支持多种语言，包括

  • 英语 (en-US) - 默认
  • 葡萄牙语 (pt-PT, pt-BR)
  • 日语 (ja-JP)
  • 中文 (zh-TW, zh-CN)
  • 土耳其语 (tr-TR)
  • 法语 (fr-FR)
  • 德语 (de-DE)
  • 西班牙语 (es-ES)
  • 捷克语 (cs-CZ)
  • 俄语 (ru-RU)
  • 拉脱维亚语 (lv-LV)
  • 还有更多...

本地化文件结构

翻译文件存储在 options/locale/ 目录中，命名约定为 locale_LANGUAGE-COUNTRY.ini。每个文件包含按部分组织的翻译。

所有语言文件都使用相同的键，这使得添加新语言或更新现有翻译更加容易。

来源：options/locale/locale_pt-PT.ini1-100 options/locale/locale_zh-CN.ini1-100

国际化结构

来源：options/locale/locale_pt-PT.ini1-100 options/locale/locale_zh-CN.ini1-100

语言选择逻辑

处理请求时，Gitea 通过以下顺序确定要使用的语言

  1. 检查 URL 语言参数
  2. 检查语言 cookie
  3. 检查用户设置中的语言偏好
  4. 检查浏览器提供的 Accept-Language 标头
  5. 回退到默认语言（通常是英语）

在模板和 Go 代码中，使用以下模式引用翻译的字符串

<!-- In templates -->
{{.i18n.Tr "key"}}

// In Go code
ctx.Locale.Tr("key")

翻译键按上下文或功能组织，例如

  • 常规 UI 元素（home、dashboard、explore）
  • 存储库特定文本
  • 问题和拉取请求的术语
  • 用户设置和配置文件
  • 身份验证消息
  • 电子邮件通知

来源： options/locale/locale_pt-PT.ini493-513

国际化流程的配置

来源： custom/conf/app.example.ini350-356

系统间的集成

配置系统和国际化框架以多种方式集成

  1. 配置决定了哪些语言可用
  2. 默认语言在配置中设置
  3. 用户语言偏好存储在用户设置中

当用户在其个人资料设置中选择语言时，此偏好设置将存储在数据库中，并用于该用户将来发送的所有请求。

常见的配置任务

添加新语言

向 Gitea 添加新语言

  1. 创建新的 locale 文件（例如，options/locale/locale_fr-CA.ini）
  2. 复制英文文件中的所有键并翻译值
  3. 在 app.ini 的 LANGS 设置中添加语言代码
  4. 重启 Gitea

更改默认语言

更改所有用户的默认语言

限制可用语言

限制用户可用的语言

最佳实践

配置

  1. 使用特定于环境的配置文件：为不同的环境（开发、测试、生产）创建单独的 app.ini 文件。

  2. 使用环境变量存储敏感信息：将密码、API 密钥和其他敏感信息存储在环境变量中，而不是配置文件中。

  3. 记录您的配置更改：修改配置时，请记录您所做的更改以及原因。

  4. 备份您的配置：在进行更改之前，请务必备份您的配置文件，尤其是在生产环境中。

来源： custom/conf/app.example.ini1-10

国际化

  1. 在部署前完成翻译：在部署之前，确保所有支持的语言都有完整的翻译。

  2. 在上下文中测试翻译：在实际的 UI 上下文中查看翻译，以确保它们具有意义。

  3. 回馈社区：如果您改进了翻译，请考虑将它们贡献回 Gitea 项目。

  4. 保持翻译一致性：在应用程序的所有部分保持术语一致性。

来源： options/locale/locale_pt-PT.ini1-10

故障排除

缺失的翻译

如果某些 UI 元素未翻译

  1. 检查您的语言的 locale 文件中是否存在该键
  2. 验证您在用户设置中选择了正确的语言
  3. 清除浏览器缓存和 cookie

配置未应用

如果配置更改未生效

  1. 检查设置是否被环境变量覆盖
  2. 验证您的 app.ini 文件中的语法
  3. 重启 Gitea 以应用配置更改
  4. 检查日志是否有任何配置解析错误