DocSpell项目Web界面翻译指南

DocSpell项目Web界面翻译指南

docspell Assist in organizing your piles of documents, resulting from scanners, e-mails and other sources with miminal effort. 项目地址: https://gitcode.com/gh_mirrors/do/docspell

前言

DocSpell作为一个文档管理系统，其Web界面的多语言支持对于全球用户至关重要。本文将详细介绍如何为DocSpell贡献新的语言翻译，即使您没有编程经验也能轻松上手。

准备工作

开发环境搭建

在开始翻译工作前，需要准备以下工具环境：

1. 版本控制工具：用于获取项目源代码
2. 构建工具：用于编译项目
3. 前端工具链：
   • Elm语言环境（0.19.1版本）
   • Node.js环境（用于npm包管理）
4. 代码格式化工具：elm-format（推荐但不强制）

项目结构了解

DocSpell的Web界面采用Elm语言开发，所有翻译相关文件位于：

modules/webapp/src/main/elm/Messages/

翻译流程详解

第一步：添加新语言支持

1. 修改UiLanguage.elm文件：

   type UiLanguage
       = English
       | German
       | 您的新语言  -- 例如: Chinese
   

2. 更新语言列表：

   all : List UiLanguage
   all =
       [ English
       , German
       , 您的新语言
       ]
   

第二步：创建翻译文件

1. 在Messages.elm中添加新语言的翻译入口：

   zh : Messages
   zh =
       { lang = Chinese
       , iso2 = "zh"
       , label = "中文"
       , flagIcon = "flag-icon flag-icon-cn"
       , app = Messages.App.zh
       -- 其他页面翻译引用
       }
   

2. 更新语言选择逻辑：

   get : UiLanguage -> Messages
   get lang =
       case lang of
           English -> gb
           German -> de
           您的新语言 -> zh
   

第三步：逐页面翻译

以登录页面为例：

1. 打开Messages/Page/Login.elm

2. 复制现有翻译模板：

   zh : Texts
   zh =
       { pageTitle = "登录"
       , loginHeadline = "登录到DocSpell"
       , submitButton = "登录"
       -- 其他字段翻译
       }
   

3. 导出新增翻译：

   module Messages.Page.Login exposing
       ( Texts
       , gb
       , de
       , zh  -- 新增导出
       )
   

第四步：实时测试

使用提供的开发脚本实时查看翻译效果：

./project/dev-ui-build.sh watch-js
./project/dev-ui-build.sh watch-css

翻译最佳实践

1. 一致性原则：保持术语统一，如"Document"在整个系统中应使用相同译法
2. 上下文理解：某些词汇在不同页面可能有不同含义，需结合上下文翻译
3. 长度控制：中文字符通常比英文短，注意UI布局适配
4. 文化适配：图标选择应考虑目标语言国家的文化习惯

常见问题解决

1. 编译错误：Elm编译器会给出详细错误信息，按照提示补充缺失的翻译分支
2. 显示异常：检查flag-icon是否正确引用，国家代码是否符合ISO标准
3. 翻译缺失：某些深层嵌套组件可能需要单独翻译，可搜索使用该字符串的位置

翻译质量检查

完成翻译后建议进行以下验证：

1. 遍历所有页面检查是否有未翻译内容
2. 测试各交互元素的悬停提示文本
3. 验证表单验证消息等动态内容
4. 检查移动端显示效果

结语

为DocSpell贡献翻译不仅能帮助全球用户更好地使用该系统，也是了解Elm语言和现代Web开发的好机会。遵循本指南，您可以系统地为项目添加完整的新语言支持。翻译过程中如遇到任何问题，项目维护者会提供必要的支持。

通过社区协作，我们可以让DocSpell惠及更多语言用户，打破文档管理的语言障碍。

docspell Assist in organizing your piles of documents, resulting from scanners, e-mails and other sources with miminal effort. 项目地址: https://gitcode.com/gh_mirrors/do/docspell