最近の悩み
- よくあるとは思うのですが、開発者向けに提供しているドキュメントを多言語対応したいときにみなさんどうしているでしょうか。
- 例えば、docusaurusを利用し、markdown で作成したドキュメントをそのままweb上に公開し見栄えよく整えるなどはよくあるんじゃないでしょうか。
- ただ、これ、開発ドキュメントが増えた際に markdown でファイルを管理し、増えたファイルを翻訳し更新かけていくのはかなり大変ですよね？
- 今回、この問題をcrowdinという OSS を使い解決できないか検証してみましたという記事です。
crowdin を使ってみての感想
- crowdin とは、オープンソースで利用できる多言語コンテンツを翻訳・管理できるサービスのようです。
-
アカウント作成、トライアルで14日間使えるらしいので、やりたいこと(docusaurusを使いmarkdoenで作成しているドキュメントの翻訳の自動化)ができるのかを検証してみます。
-
ドキュメントを読んでいくと crowdin と docusaurus のインテグレーション機能があるようです。
- アカウントを作成し、[Integrations] のタブを見るといくつか外部のサービスとIntegrationできそうで、今回はGithubを利用させていただきました。
- 翻訳したいファイルと翻訳後の置き場など、ただGithubのリポジトリとsyncするだけだと crowdin は分かりません。
- そこで sync したいリポジトリに設定ファイルを配置する必要があります。
crowdin cli のインストール
* 設定ファイルの作成や、package.json 内のスクリプトにcliコマンドの設定もできます。
> brew install crowdin@3
package.json
{
"scripts": {
// ...
"write-translations": "docusaurus write-translations",
"crowdin": "crowdin"
}
}
- 初期化コマンドを使用すると crowdin.yml というファイルが作成され、ここに記載するものが翻訳元と翻訳後のファイルをどこに配置するのかという設定になります。
crowdin init
crowdin.yml
project_id: '123456'
api_token_env: CROWDIN_PERSONAL_TOKEN
preserve_hierarchy: true
files:
# JSON translation files
- source: /i18n/en/**/*
translation: /i18n/%two_letters_code%/**/%original_file_name%
# Docs Markdown files
- source: /docs/**/*
translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
# Blog Markdown files
- source: /blog/**/*
translation: /i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%
- 上記の設定ファイルを crowdin と sync したリポジトリの該当ブランチにコミットすると下記のように自動でスキャンが始まります。
- スキャンが完了すると下記のように、どのファイルがどこまで対象の翻訳ができているのかを確認することができます。
-
例えば、特定のファイルを選択したときにどのように翻訳するのか翻訳後の言葉の候補を提示してくれるようです。
-
下記のように翻訳候補を選択し、「save」を押すと crowdin 上にデータが保存されるようで、それを手元のプロジェクトに cli 経由で落として使う形のようですね。
- 翻訳後は、下記のコマンド(crowdinをnpmスクリプトに仕込めば)で翻訳したものをダウンロードする形となります。
> npm run crowdin download
- また、下記のようなスクリプトを設定しておけば、crowdin 上に自身が翻訳したもの他の人が翻訳したものが存在すれば同期をとりながら翻訳することができます。
package.json
{
"scripts": {
"crowdin:sync": "docusaurus write-translations && crowdin upload && crowdin download"
}
}
結論
- crowdin についてを利用する場合、確かに翻訳を手分けして行なっている場合に関しては、翻訳の状態が可視化され分かるので便利な反面、使い方のナレッジ共有と翻訳される単語も翻訳しながら学習させていったりしないといけないので、手間はかかかりそうです。
- イメージとして、例えば英語版の新しい文章が追加されたり、変更があった場合に自動でGithub上でPRまで上げてくれる感じだと嬉しいのですが、そこまでできない気がするので、導入はもう少し待てからという所感でした。