Ansible 文件翻译备忘录

1 年 ago
清, 扬
4 minutes

首先

现在正在将Ansible文档翻译成日文。目前进展还不大，但会保留翻译过程的笔记。

对于目标读者，无论是对Ansible感兴趣的人还是对文档翻译工作有兴趣的人。

另外，正在翻译的 HTML 文件已在下一页公开。

    Ansible ドキュメント

源代码在下面的位置。 de .)

    • kyoshidajp/ansible

 

    • kyoshidajp/ansible-modules-core

 

    kyoshidajp/ansible-modules-extrax

整治环境

环境

我正在以下环境中进行工作和操作。

翻译任务机器

Mac OS X 10.10.1

发布机器

Amazon Linux AMI 2014.09 发行版

有一些在上述环境下才能运作的内容。

获取源代码

首先，在翻译工作站上获取包含文档和源代码的文件。

由于 Ansible 的源代码在 GitHub 上进行管理，因此需要准备一个 GitHub 账户。在登录 GitHub 的情况下，访问 ansible/ansible 并通过点击” Fork” 按钮创建自己的代码仓库。

fork.png

然后，将其克隆到适当的翻译工作目录中的机器上。

$ git clone https://github.com/kyoshidajp/ansible.git

之后，创建并切换到用于翻译工作的分支。这次命名为”japanization”。

$ git checkout -b japanization devel

我会在下一个代码仓库中执行相同的任务。

    • ansible/ansible-modules-core

 

    ansible/ansible-modules-extras

创建构建环境

要构建Ansible文档，需要准备Sphinx文档工具的执行环境。

在我的情况下，我已经安装了，但是例如可以通过setuptools来安装。

$ sudo curl https://bootstrap.pypa.io/ez_setup.py -o - | python
$ sudo easy_install sphinx

然后，在工作目录中进行构建。

$ cd ~/ansible
$ make webdocs

每个HTML文件将会生成在docsite/htmlout。

在翻译工具机上执行下列指令后，将会在默认的网络浏览器中显示文档的索引页面。

$ open docsite/htmlout/index.html

构成 –

ansible的文件文档（需要翻译的文件）大致分为以下3种类型。

    1. ansible/docsite/rst 文件下的 rst 文件

 

    1. 模块的 py 文件

 

    其他文件

ansible/docsite/rst以下的rst文件是reStructuredText格式。

模块的py文件是在ansible-module-core和ansible-modules-extras各种模块的主体中编写的docstring，并会被转换为rst格式。

其他的例子可能是

    • ansible/hacking/templates/rst.j2

 

    ansible/docsite/_themes/srtd/breadcrumbs.html

等等，变得更加细致入微。

UnicodeDecodeError 的處理方式

在源代码中包含日语时，根据环境可能会在构建时出现 UnicodeDecodeError 错误。

Traceback (most recent call last):
  File "../hacking/module_formatter.py", line 443, in <module>
    main()
  File "../hacking/module_formatter.py", line 438, in main

... 略 ...

    return self.environment.handle_exception(exc_info, True)
  File "/Library/Python/2.7/site-packages/jinja2/environment.py", line 742, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "../hacking/templates/rst.j2", line 105, in top-level template code
    @{ plainexamples | indent(4, True) }@
  File "/Library/Python/2.7/site-packages/jinja2/filters.py", line 442, in do_indent
    rv = (u'\n' + indention).join(s.splitlines())
UnicodeDecodeError: 'ascii' codec can't decode byte 0xe7 in position 2: ordinal not in range(128)
make: *** [modules2] Error 1

为了避免这个问题，我们将默认编码设为 utf-8。例如，您可以参考以下页面。

    Python – sitecustomize.py を使わず usercustomize.py を使おうね – Qiita

开始翻译

在文本编辑器中编辑目标文件，开始翻译工作。我的情况是，我使用 Atom 编辑器，但只能利用它的记事本功能，没有更多的应用。

已编辑的文件未提交后，可以根据左侧的树形图标变化来明确判断。

atom.png

只要使用GitHub客户端（例如GitHub for Mac），就可以覆盖对历史记录和更改的确认功能，因此基本上什么编辑器都可以使用。

有一个专门用于翻译的开源软件 OmegaT，但我还未使用过它。

在编辑器上保存时进行构建和预览。

当进入翻译任务机器的实际翻译阶段时，

    1. 执行构建命令。

 

    1. 确认命令成功，并在浏览器中预览。

 

    编辑后返回步骤 1。

每个周期都重复这个过程。由于每次都是手工操作，这样太麻烦了，所以我们使用Guard和AppleScript来自动化。

首先，我们要创建一个通过命令行在 Google Chrome 中重新加载（或加载）文档的 AppleScript 脚本。

将 file_url 的值更改为打开（或创建）HTML 文件的目录，可以是任何适当的路径。

tell application "Google Chrome"
    activate
    set file_url to "file:///Users/kyoshida/ansible/docsite/htmlout/"

    if (count every window) = 0 then
        make new window
    end if

    set found to false
    set theTabIndex to -1
    repeat with theWindow in every window
        set theTabIndex to 0
        repeat with theTab in every tab of theWindow
            set theTabIndex to theTabIndex + 1
            if theTab's URL starts with file_url then
                set found to true
                exit
            end if
        end repeat

        if found then
            exit repeat
        end if
    end repeat

    if found then
        tell theTab to reload
        set theWindow's active tab index to theTabIndex
        set index of theWindow to 1
    else
        set index_url to {file_url, "index.html"} as text
        tell window 1 to make new tab with properties {URL:index_url}
    end if
end tell

如果您是 Firefox 或 Safari 用户，下一页可能会对您有所帮助。

    • Auto Reload :: Add-ons for Firefox

 

    • Andrew Griffin : Digital Designer — Auto Refresh Safari Extension

 

    AppleScript: How to reload a Safari window with… | Apple Support Communities

接下来，使用 gem 安装 Guard，并执行初始命令。

$ bundle exec guard init

在当前目录下创建一个 Guardfile，并进行以下设置。

guard :shell do
  watch(/(.*).[rst|py]/) {|m| `cd ~/ansible/docsite && make htmldocs && cd ~/guard/ && osascript reload.scpt` }

用-w选项指定存在要监视的文件的目录，并执行。

$ bundle exec guard -w ansible/docsite/rst ansible-modules-core ansible-modules-extras

在保存文件时进行构建，如果构建成功，则进行预览。

顺便说一下，在包括模块在内的构建过程可能会花费一些时间（在我的环境中大约数十秒）。为了缩短从保存到预览的时间，有一种方法是在构建时删除一些 rst 文件，或者注册到 cron 并定期进行构建，以便在需要时进行预览。

在 GitHub 上提交（push）后进行构建和部署。

在公共计算机上进行的反映处理遵循以下流程。

    1. 从GitHub上获取最新的源代码

 

    1. 进行构建

 

    如果构建成功，则将其转移到公共目录中

使用Jenkins和GitHub插件，可以在git push时自动完成，避免手动操作这一麻烦任务。

另外，在这个任务中，我们将安装Apache，这样你就可以在网上发布翻译好的页面了。

Jenkins的安装

首先，安装Jenkins。将Jenkins的运行机器设置为与公开机器相同。

$ sudo wget -O /etc/yum.repos.d/jenkins.repo http://pkg.jenkins-ci.org/redhat/jenkins.repo
$ sudo rpm --import http://pkg.jenkins-ci.org/redhat/jenkins-ci.org.key
$ sudo yum -y install jenkins

为了在子目录中运行Jenkins，需要更改/etc/sysconfig/jenkins文件中的JENKINS_ARGS。

JENKINS_ARGS="--prefix=/jenkins"

然后，开始运行服务。

$ sudo service jenkins start

安装Apache

安装 Apache 网页服务器。

另外，还要进行反向代理设置，以便通过端口号80访问Jenkins。

$ sudo yum -y install httpd
$ sudo vi /etc/httpd/conf/httpd.conf

<VirtualHost *:80>
  ProxyPreserveHost Off
  ProxyPass /jenkins/ http://localhost:8080/jenkins/
  ProxyPassReverse /jenkins/ http://localhost:8080/jenkins/
</VirtualHost>

启动Apache。

$ sudo service httpd start

如果从浏览器访问 http://服务器名称/jenkins 并显示 Jenkins 的界面，则表示 Jenkins 安装已完成。

Jenkins的任务注册

从Jenkins界面的”管理Jenkins”->”插件管理”中安装Git插件、GitHub API插件、参数触发插件。

然后，从”创建新任务”中创建一个任务。

工作名称

 

更新Ansibledoc

 

工作类型

 

自由风格项目构建

工作配置可以这样设置。

源码管理

 

Git

 

存储库URL

 

https://github.com/kyoshidajp/ansible-modules-core.git

 

要构建的分支

 

日本化

 

构建触发器

 

勾选“当GitHub接收到更改时进行构建”。

此外，选择“添加构建步骤”，然后选择执行Shell，并将其内容设置为以下内容。

make webdocs
rsync -vr --delete docsite/htmlout/ /公開ディレクトリ/

为了试试运行任务并确认结果，我们将执行一次任务。

我们还将为下一个模块创建相应的任务。

    • ansible/ansible-modules-core

 

    ansible/ansible-modules-extras

在每个构建的“执行程序”中，我们将同步到ansible/modules/目录下的核心(core)和附加(extras)文件夹。

rsync -vr --delete --exclude ".git/" ./ ../../ansible のジョブ名/workspace/lib/ansible/modules/core

或者

rsync -vr --delete --exclude ".git/" ./ ../../ansible のジョブ名/workspace/lib/ansible/modules/extras

成为。

因为这些是模块，所以在“构建后处理”中，如果构建（获取源代码）成功，就会执行主要任务（任务名称：更新ansible文档）的操作。

请勾选「仅在构建稳定时触发」选项。

最后，我们将分别确认每个工作的成功。

GitHub的设置

下面进行从 GitHub 调用之前创建的 Jenkins 任务的设置。

在我的GitHub项目中，“设置”->“Web钩子和服务”的服务-添加服务中选择Jenkins（GitHub插件）。

将「Jenkins挂钩URL」注册为Jenkins的URL + github-webhook/。

对于我的情况而言，会是这样的。

http://www.kyoshida.jp/jenkins/github-webhook/

勾选「Active」，然后点击「Test service」按钮进行访问确认。

Okay, the test payload is on its way.

如果显示出这样的结果，那就是没问题了。

只需在中国本地用中文解释一次：尝试随意推送文件到git，如果作业开始运行，则设置完成。

但是，这也需要对存储库进行配置。也就是说

    • ansible/ansible-modules-core

 

    ansible/ansible-modules-extras

我们也会对此进行。

关于翻译

规则

关于翻译，我认为其实有一定的规则是最好的。但是，因为只是暂时开始了，所以还没有进行实践。

在我读了很多方面之后

    翻訳について | Djangoと日本の仲間たち

这个非常有参考价值。特别是将原始的英文翻译注释掉保留下来，看起来很不错，因为其他人可以在后面进行确认。

我觉得分支目标版本的时候也许不太好，是不是？

另外，参考了下一页关于 TIPS 的内容。

    ドキュメントの翻訳にSphinxを使う (i18n非利用) — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会

怎么翻译固有名词

有关“playbook”和“inventory”等专有名词（专业术语）的翻译有以下几种模式。

    1. 保持原样

设定为Playbook(剧本)和Inventory(清单)
在首次出现时设定为Playbook(剧本)和Inventory(清单)

由於感覺上不太順暢，且對於第三點不太清楚初次出現的時間，（或者在未來的更新中進行了變更但不容易察覺），因此我們保持原樣。

请教您关于如何前进的方法。

起初的计划是，在完成介绍和玩法手册的基础部分之后，按照各种模块中经常使用的和词汇表等内容的顺序推进。

虽然在这方面进展缓慢，但我也开始先着手处理模块和Ansible Tower了。

最后

我长篇大论地写了之后，再次回顾时意识到自己正在进行着毫无明确计划的工作。特别是在没有规则的情况下，未来可能会出现问题的可能性很高。

不过，我们也知道仅仅解决所有不确定因素后才开始工作的方法永远无法实现。从某种意义上说，或许着手开始是件好事。

由于重要的翻译进展不尽如人意，我希望能在年末年初的假期里尽可能多地推进。

另外，我想可能有很多翻译不准确的地方。由于我们接受 PullRequest，请如果您有任何疑虑，请不要客气与我们联系。

在最后关头

很抱歉，由于时间不足，我无法将包含创建上述环境的playbook放在这里。

我在Galaxy上找到了Stouts.jenkins，所以如果使用它，也许是可以的。

✖
广告
将在 10 秒后关闭
bannerAds