使用 po4a 进行技术文档翻译：从入门到实践

在开源项目中，文档的多语言支持是提升项目影响力的重要环节。最近在为 Yii3 框架文档添加简体中文翻译时，我深入使用了 po4a 这个强大的翻译工具。本文将分享使用 po4a 进行技术文档翻译的完整流程和实践经验。

什么是 po4a？

po4a（PO for Anything）是一个基于 gettext 的文档翻译工具，最初为 Debian 项目开发，但现在已经广泛应用于各种文档翻译场景。它的核心优势在于：

• 格式无关：支持 Markdown、POD、XML、HTML 等多种格式
• 版本控制友好：翻译文件（.po）是纯文本，易于纳入 Git 管理
• 增量更新：源文件更新时，自动合并已有翻译，避免重复工作
• 团队协作：支持多人协作翻译，便于分工

项目结构

在开始之前，先了解典型的 po4a 项目结构：

docs/
├── _translations/        # 翻译配置和 PO 文件
│   ├── po4a.conf         # 主配置文件
│   ├── pot/              # 模板文件（.pot）
│   └── po/               # 翻译文件（.po）
│       └── zh-CN/        # 简体中文翻译
├── src/                  # 源文件和翻译输出
│   ├── en/               # 英文源文件
│   └── zh-CN/            # 简体中文翻译输出

这种结构将翻译工作与源文件分离，既保持了源文件的整洁，又便于管理翻译进度。

配置 po4a

po4a 的核心是配置文件 po4a.conf。以下是一个典型的配置：

[po4a_langs] ru id es zh-CN

[po4a_paths] pot/$master.pot $lang:po/$lang/$master.po

[options] opt:"--verbose" opt:"--addendum-charset=UTF-8" opt:"--localized-charset=UTF-8" opt:"--master-charset=UTF-8" opt:"--master-language=en_US" opt:"--porefs=file" opt:"--msgmerge-opt='--no-wrap'" opt:"--wrap-po=newlines"

[po4a_alias:markdown] text opt:"--option markdown" opt:"--option keyvalue" opt:"--option yfm_keys=title,description,menu_title,details,name,text,tagline" opt:"--addendum-charset=UTF-8" opt:"--localized-charset=UTF-8" opt:"--master-charset=UTF-8" opt:"--keep=0"

[type: markdown] ../src/index.md $lang:../src/$lang/index.md pot=index.md
[type: markdown] ../src/cookbook/preface.md $lang:../src/$lang/cookbook/preface.md pot=cookbook_preface.md

配置说明：

• [po4a_langs]：指定要翻译的语言列表
• [po4a_paths]：定义 POT 和 PO 文件的路径模式
• [options]：全局选项，如字符编码、引用格式等
• [po4a_alias:markdown]：为 Markdown 格式定义别名和特定选项
• [type: markdown]：映射源文件、翻译文件和对应的 POT 文件

翻译流程

第一步：初始化翻译

首次使用时，运行以下命令生成初始的翻译文件：

cd _translations
po4a po4a.conf

这个命令会： 1. 扫描所有配置的源文件 2. 提取可翻译字符串到 POT 模板文件 3. 为每种语言创建对应的 PO 文件 4. 生成初始的翻译 Markdown 文件（此时还是英文）

第二步：翻译 PO 文件

PO 文件是翻译的核心，格式如下：

#. type: Plain text
#: ../src/cookbook/preface.md
msgid "Yii is a high-performance, package-based PHP framework."
msgstr "Yii 是一个高性能、基于包的 PHP 框架。"

• msgid：原始字符串（英文）
• msgstr：翻译后的字符串
• #.：注释，说明字符串的来源和类型

推荐的翻译工具

1. Poedit（图形界面）

Poedit 是最流行的 PO 文件编辑器，提供直观的界面和实时预览。

# macOS
brew install --cask poedit

# Ubuntu
sudo apt-get install poedit

# 使用
poedit _translations/po/zh-CN/cookbook_preface.md.po

2. Lokalise（在线协作）

适合团队协作，支持多人同时翻译，提供翻译记忆库。

3. Weblate（开源平台）

完全开源的在线翻译平台，支持 Git 集成，适合开源项目。

第三步：生成翻译文档

完成翻译后，运行 po4a 生成最终的 Markdown 文件：

cd _translations
po4a po4a.conf

po4a 会： 1. 读取所有语言的 PO 文件 2. 根据翻译生成对应的 Markdown 文件 3. 保留未翻译的内容为英文 4. 保持原始的 Markdown 格式

第四步：验证翻译结果

检查生成的文件：

# 查看翻译进度
po4a --no-update po4a.conf | grep "zh-CN"

# 输出示例：
# ../src/zh-CN/cookbook/preface.md is 75% translated (9 of 12 strings).

# 查看生成的文件
cat src/zh-CN/cookbook/preface.md

常用命令

查看翻译统计

cd _translations
po4a --no-update po4a.conf | grep "zh-CN"

更新翻译文件

当源文件更新后，更新 PO 文件：

cd _translations
po4a po4a.conf

这会自动合并新的翻译字符串，保留已有翻译。

仅生成 Markdown（不更新 PO）

如果只想从现有 PO 文件生成 Markdown：

cd _translations
po4a --no-update po4a.conf

检查 PO 文件语法

# 检查所有文件
find _translations/po/zh-CN -name "*.po" -exec msgfmt --check-format {} \;

# 检查特定文件
msgfmt --check-format _translations/po/zh-CN/cookbook_preface.md.po

翻译最佳实践

1. 保持术语一致性

技术文档的翻译最重要的是术语一致性。建议：

• 创建项目术语表（glossary）
• 在 Poedit 中使用术语表功能
• 参考已有翻译保持一致

例如： - “framework” → “框架” - “middleware” → “中间件” - “dependency injection” → “依赖注入”

2. 处理特殊字符串

Markdown 格式

保留 Markdown 语法，不要翻译：

msgid "**Bold text** and `code`"
msgstr "**粗体文本**和`代码`"

变量占位符

保留变量名不变：

msgid "Hello, {name}!"
msgstr "你好，{name}！"

复数形式

处理单复数：

msgid "One file"
msgid_plural "{count} files"
msgstr[0] "一个文件"
msgstr[1] "{count} 个文件"

3. 处理模糊翻译

po4a 会将部分匹配的翻译标记为 “fuzzy”（模糊）：

• 检查模糊翻译是否准确
• 确认后移除模糊标记
• 或重新翻译以确保准确性

4. 代码和配置文件

对于代码示例和配置：

• 通常不翻译代码本身
• 只翻译注释和说明文字

• 保留变量名、函数名、类名等

  msgid "Create a file `config/common/sentry.php`"
  msgstr "创建文件 `config/common/sentry.php`"
  

实战经验

问题 1：PO 文件语法错误

错误信息：

msgfmt: found 1 fatal error

解决方案：

# 检查哪个文件有问题
find _translations/po/zh-CN -name "*.po" -exec msgfmt --check-format {} \;

# 修复语法错误（通常是引号或换行问题）
# 然后重新生成
po4a po4a.conf

问题 2：翻译未生效

可能原因： - PO 文件未保存 - msgstr 为空 - 字符串标记为 fuzzy

解决方案：

# 检查翻译状态
po4a --no-update po4a.conf | grep "zh-CN"

# 确保所有 msgstr 都有内容
# 移除 fuzzy 标记（如果翻译正确）

问题 3：Markdown 格式错误

可能原因： - 翻译中破坏了 Markdown 语法 - 特殊字符未正确转义

解决方案： - 检查生成的 Markdown 文件 - 确保保留原始的 Markdown 格式 - 特别注意代码块、链接和表格

团队协作

分工翻译

对于大型文档项目，可以按模块分工：

# 按目录分工
- cookbook/ → 翻译者 A
- guide/ → 翻译者 B
- internals/ → 翻译者 C

代码审查

建立翻译审查流程：

1. 翻译者提交 PR
2. 审查者检查术语一致性和准确性
3. 合并到主分支
4. 运行 po4a 生成最终文档

持续集成

将翻译流程集成到 CI/CD：

# .github/workflows/translation.yml
name: Translation
on:
  push:
    paths:
      - '_translations/po/zh-CN/**'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Generate translations
        run: |
          cd _translations
          po4a po4a.conf
      - name: Commit changes
        run: |
          git config user.name "GitHub Actions"
          git add src/zh-CN/
          git commit -m "Update translations"
          git push

总结

po4a 是一个强大而灵活的文档翻译工具，特别适合技术文档的多语言支持。通过合理配置和遵循最佳实践，可以高效地完成文档翻译工作。

关键要点：

1. 配置先行：正确配置 po4a.conf 是成功的基础
2. 工具辅助：使用 Poedit 等工具提高翻译效率
3. 术语一致：保持术语一致性是技术文档翻译的关键
4. 持续更新：源文件更新时及时同步翻译
5. 团队协作：建立分工和审查机制，保证翻译质量

参考资源

• po4a 官方文档
• GNU gettext 文档
• Poedit 用户手册
• Yii3 文档项目

希望本文能帮助你在项目中高效地使用 po4a 进行文档翻译。如果你有任何问题或建议，欢迎在评论区交流！

文章归档

文章日历

文章标签

• Linux
• Go
• Yii
• 新浪
• CentOS
• PHP
• Git
• WSL
• Composer
• Mac
• PDF
• 入职
• Bootstrap
• 翻译
• UCenter
• 厦门
• 出差
• 长沙
• 湖南卫视
• 微博
• Tengine
• YUI
• 泰国
• pecl
• 优化
• GitLab
• 迁移
• rootless
• 年会
• 生日
• Tengin
• RedHat
• Sphinx
• cygwin
• Windows
• Tmux
• Zsh
• 升级
• MySQL
• sql_mode
• Shadowsockets
• 面向对象
• HTTP
• 状态码
• grep
• unoconv
• PPT
• Nginx
• htpasswd
• golang

最新评论

• 
  崔亮 于 19-05-23 评论了

  Tengine 2.2.2 配置 http2 协议出现的坑
• 
  王媛 于 19-01-31 评论了

  Yii China 是官方唯一认可的中文社区
• 
  三杯蛙 于 19-01-24 评论了

  Go 语言中 json 的操作以及常见问题
• 
  三杯蛙 于 19-01-24 评论了

  新浪赴泰国曼谷和芭提雅团建
• 
  巡洋舰 于 18-09-05 评论了

  CentOS 安装 PHP7
• 
  小不点 于 11-03-02 评论了

  WordPress 如何控制每页显示的条数
• 
  白领厕工 于 10-12-22 评论了

  关于 phpMyAdmin 免输入用户名和密码，直接进入管理界面
• 
  清晨的欣赏 于 10-08-04 评论了

  PHP 5.4 的新特性
• 
  易赛官网 于 10-07-27 评论了

  PHP 5.4 的新特性
• 
  文秘之家 于 10-07-17 评论了

  PHP 5.4 的新特性

友情链接

• PHP 生态圈
• Yii Framework 中文网
• Yii CMS
• Vim Wiki