OpenWrt / LEDEのWebUI “LuCI” を翻訳する

少し前から翻訳に携わっているOpenWrt/LEDE-Projectで利用されているWebUI “LuCI” ですが、某所にて全体を通してのやり方について尋ねられたことがあったので、今後翻訳や修正に参加する人がもっと増えれば、ということで書き留めることにしました。
少し前にLEDE 17.01向けLuCIのブランチ(lede-17.01)が切られましたが、今回はmasterブランチのみに絞って書きます。

今回記事がかなり長いので、記事内リンクを設置。


作業環境

翻訳の主体となる .po ファイルの編集とGitの操作のみであればWindowsのみでも可能。ただし、LuCI側で用意されているツールを利用する場合Linux系の環境が必要。
あくまで筆者自身のやり方なので、若干面倒な気がしなくもないけど悪しからず。

Windows環境

  • OS: Windows 10

    言わずと知れたWindows系最新OS。

  • Git環境: Git for Windows

    筆者自身は、主にgit-bashを使用。

  • gettext(.po)エディタ: Poedit

    OSDN / SourceForgeのPoeditはバージョンが古くなっているため、公式サイトからのダウンロードを推奨。
    無償版と有償版があり、違いはネット上のデータベースからの翻訳サジェスト機能や詳細な統計情報など。
    LuCIの翻訳では、自身の英語力にもよるものの無償版で十分。ちなみに、筆者に英語力はありません。

  • LuCIツール環境: WSL (Windows Subsystem for Linux)

    Windows 10 Anniversary Updateより正式に追加(これ自体はまだbeta機能)された、CUIなLinux (Ubuntu)環境。
    LuCI側で用意されているツール類はWindows環境では動作しないため、これらのツールを使う場合は一旦WSLで作業。


Linux環境

現在普段使用するPCにLinux環境が無く確認できないため、詳しくは書かない。

  • OS: 任意のLinux ディストリビューション

  • Git環境: git-coreなど

  • gettext(.po)エディタ: Poedit

    WSLで試すも、1.8.11ソースコードからのインストールが上手くいかなかった。

    apt-get install poedit

    でインストール可能だが、旧バージョンの1.5.4がインストールされる。

  • LuCIツール環境: 各shell(bash等)


必要なもの

  • GitHubアカウント

    翻訳した .poなどはGitHubを通してPull Request (PR)を行い、メンテナが確認したうえでマージ(取り込み)されるため、GitHubのアカウントが必要。

  • 任意: 英和辞書等

    翻訳の際に使ったり。筆者はインターネット上の辞書サイトを見たりしている。

  • ある程度のネットワーク, PC関連知識

    一般的な英単語だけでなく、専門用語の単語もある程度入ってくる。

  • 多少の英語読解力

    どちらかというと、そこまで難易度の高い英単語が登場する頻度は多くは無い。
    ただ、やはり慣用句的なものが使用されることが多少あったり、また、GitHubでPRを行う際にメンテナから英語による指摘が入る場合があるため、それに従って正確に対応する必要がある。

  • 根気

    筆者の様に、あまり英語力が無い状態で翻訳を行おうとすると、辞書等とエディタを行ったり来たり、Google翻訳で再翻訳(訳した日本語→英語)を繰り返したり(できる限りの翻訳の信頼性)するため、非常に時間が掛かる。
    英語の読解力に長けている場合は、スムーズに翻訳できると思うので恐らく問題無し。

    2017/02/23 追記:Twitterで興味深い記事が流れてきたのでリンク。
    Web翻訳の結果をオープンソースソフトウェア(OSS)の翻訳に突っ込んではいけませんという話 – いくやの斬鉄日記

  • チャレンジ精神

    翻訳されていない箇所を見つけた場合、「誰かが訳すだろう」ではまず翻訳されない。実際、筆者が翻訳を始めた時点で確認できた限りでは、日本語訳の最終更新が2013年だったが(恐らくそれ以降追加や変更された)未訳箇所が大量にあった。
    見つけたら、「英語があまり得意でないからやらない」「誰かがやるだろう」ではなく、「ならば自分がやる」という気持ちを持つ。もちろん、自信を持てない箇所を無理に翻訳する必要は無く、未訳として残してPRを行っても問題ない


翻訳の流れ

実際の翻訳作業の流れ。基本的には、LuCIのGitHubリポジトリ内にある Contributing Guidelines (CONTRIBUTING.md) の説明に従う。

準備

初回や環境が変わる場合のみ必要な作業。GitHubのアカウントは既に取得しているものとし、GitとPoeditのインストールも済んでいるものとする。
また、LuCIのツールを利用した作業を行う場合は、WSLにも同様にGitの設定が必要になる。

  • Gitの設定

    Git操作を行うにあたり、必要な設定を行う。具体的にはユーザー名とメールアドレス。
    LuCIは後で説明する通り、コミット(作業内容を確定する)に自分の本名でのサインが必要であるため、筆者はユーザー名に本名を登録した(ついでにGitHubのアカウントも表示名を本名に変更した)。
    サインを手動で記述する場合は、GitHubに登録したハンドルネームなどでも(恐らく)問題ない。

    git config --global user.name "(本名または任意のユーザー名)"
    git config --global user.email "(自分の公開用メールアドレス)"
    

    例:

    git config --global user.name "musashino205"
    git config --global user.email "hoge@gmail.com"
    

    設定した内容は、

    git config --global --list
    

    で確認できる。
    名前は漢字ではなく英語表記。
    メールアドレスはGitHub上で公開されるほか、コミットにもサインと一緒に残るため、それでも問題ないアドレスを使用する。Gmailなどのフリーメールで問題ない。

  • LuCIリポジトリのフォーク

    自分のGitHubアカウントに、LuCIリポジトリをコピー(フォーク)する。GitHubのWeb上で、右上にある Fork ボタンから操作を行う。

  • フォークしたリポジトリを作業環境にclone

    自分のアカウントにフォークしたリポジトリを、Gitを利用して作業環境にclone(ダウンロード)する。
    cloneする場所は任意の場所で問題ない。

    git clone https://github.com/(自分のGitHubユーザー名)/luci.git
    

    例(git-bash):

    Tofu@Tofu-H170W10 MINGW64 /
    $ cd ~/git
    
    Tofu@Tofu-H170W10 MINGW64 ~/git
    $ git clone https://github.com/musashino205/luci.git
    Cloning into 'luci'...
    remote: Counting objects: 92014, done.
    remote: Compressing objects: 100% (7/7), done.
    remote: Total 92014 (delta 0), reused 0 (delta 0), pack-reused 92007
    Receiving objects: 100% (92014/92014), 28.56 MiB | 2.43 MiB/s, done.
    Resolving deltas: 100% (53601/53601), done.
    Checking out files: 100% (2474/2474), done.
    
    Tofu@Tofu-H170W10 MINGW64 ~/git
    $
    

    ハイライトされている行が入力したコマンド。

    注: Windowsでは、”~/” の場所は

    C:\Users\(ユーザー名)\
    

    になる。

  • フォーク元リポジトリを登録する

    後でLuCIのフォーク元リポジトリが更新された際に、自分のフォークとの差異を取り込むためにフォーク元リポジトリをGitに登録しておく。
    この登録は、行った環境でのみ機能する。(PC1 → PC2に作業環境を変更した、などの場合は再登録が必要)

    git remote add upstream https://github.com/openwrt/luci.git
    


翻訳する

実際に翻訳していく。


  • 通常の手順

    • 作業用ブランチを切る

      作業環境でcloneしたLuCIのディレクトリに入ると、最初の状態ではmasterブランチ(枝)にいる。
      このmasterブランチは変更せず、作業中の状態との比較や後にPRした変更内容がLuCIに取り込まれた際に、その変更を自分のフォークにも取り込めるように残しておく。
      翻訳作業を開始するにあたって、masterブランチから新規のブランチを切り(枝分かれさせ)、そのブランチに移動して作業を行う。

      git checkout -b (任意の新規ブランチ名)
      

      例(Adblockの日本語訳を更新):

      git checkout -b adblock-upd-ja
      

      上記コマンドでは、新規ブランチの作成と同時にそのブランチへの移動も行われる。

    • poファイルを編集(翻訳)する

      LuCIでは、画面上に翻訳されたテキストを表示するためにgettextというシステムが利用され、その翻訳が記述されるのが .poという拡張子を持つファイルになっている。
      poファイルはLuCIのベース部分および各アプリケーションごとに分離され、それぞれのディレクトリに存在している。

      • ベース
        modules/luci-base/po/ja/
      • アプリケーション
        applications/

        • Adblock
          luci-app-adblock/po/ja/
        • Commands
          luci-app-commands/po/ja/
        • (以下省略)

      これらのpoファイルに、提示される英語のソーステキストに対する翻訳を記述していく。
      可能であれば、ルーター上で実際にLuCIの表示を見て、それぞれのテキストがどこでどのように表示されるものであるか確認しながら翻訳すると、不自然な翻訳になりにくい(です/ます調や文の切り方など)。
      後は根気で頑張って翻訳。先述の通り、不安な部分まで無理に訳す必要は無く、そこは未訳(訳が空)で留め置く。

      ※注: poファイルが存在しないアプリケーションの場合、luci-app-(アプリケーション名(以下 “App名”))/po/templates 以下にテンプレートが存在するので、それをもとに po/ja 以下に (App名).po のファイル名で新規にpoファイルを作成する。その際、poファイルのファイル名が正しくないと、翻訳を行ってもLuCIがアプリケーションのpoファイルを見つけられず翻訳が適用されない。
      テンプレートすら存在しない場合、ツールを利用してテンプレートを生成する必要がある。その場合、テンプレートが存在しない場合の手順 を参照。

      自分にできる範囲での翻訳が完了したら、Poeditで保存して終了し、Git環境に戻る。

    • GitHubのフォークに変更内容を適用する

      追加した翻訳などの変更内容をGitHubに適用する。
      Gitのaddコマンドを用いて変更内容を含ませ、

      git add ./
      

      ※この際、改行コードについて警告が出る場合がある。筆者の場合特に問題なかったので無視した。

      commitコマンドで変更内容の確定を行う。この際、作業した人の名前をコミットメッセージに含める必要がある。
      Git環境に実名を登録した場合は “–signoff” 引数を付け、登録していない場合は何も引数を付けない。
      実名登録済み:

      git commit --signoff
      

      実名未登録(ハンドルネームなど):

      git commit
      

      するとGit環境で既定に設定されているテキストエディタが開くため、そこでコミットメッセージを編集する。特に設定していなければ、恐らく “vi” が使用される。
      コミットメッセージについてもガイドラインでおおよその書き方が指定されている。
      まず、コミットのsubject(主題)は以下の形にする。

      luci-app-(App名): (簡潔な変更内容)

      次に、一行間隔を空けてある程度詳細な変更内容についての説明を書く。
      “最近追加された文字列の日本語訳を追加した(英文)” や、単に “日本語訳を追加した(英文)” など。詳細にとは言っても、そこまで厳密には求められないのでこの程度でもOK。
      ただし、説明を何も書かない場合、この後PRを行った際にメンテナから修正するよう指摘が入る場合がある。
      commitコマンドを “–signoff” 引数を付けて実行した場合は以下の通りになっているか確認する。引数を付けなかった場合は、以下の通りに記述する。

      (説明の後一行空ける)
      Signed-off-by: (自分の実名(英語)) <(メールアドレス)>
      

      例:

      
      Signed-off-by: YAMADA Tarou <tarou@gmail.com>
      

      名前とメールアドレスは適当なもの(私のではない)を使用しました。指摘いただいた場合は変更または削除します。
      コミットメッセージを記述したら、保存してエディタを終了する。

      次にpushコマンドを使用し、GitHubのフォークに翻訳した内容を適用する。

      git push origin --all
      

      この時、”テンプレートが存在しない場合の手順” を行っていた場合のみ、pushがGitHubに受け入れられず拒絶 (reject) される。
      これは先に一旦コミットの取り消しを行った結果、GitHubと作業環境で進み具合が異なるために発生する。
      この場合、GitHub上も作業環境で先に取り消したコミットはそのまま取り消して翻訳後のコミットにまとめるため、強制的にpushを行ってGitHubに適用する。

      git push -f origin --all
      

      pushの拒否と強制pushの例:

      Tofu@Tofu-H170W10 MINGW64 ~/git/luci/applications/luci-app-adblock/po (tool-test)
      $ git push origin --all
      To https://github.com/musashino-build/luci.git
       ! [rejected]        tool-test -> tool-test (non-fast-forward)
      error: failed to push some refs to 'https://github.com/musashino-build/luci.git'
      hint: Updates were rejected because the tip of your current branch is behind
      hint: its remote counterpart. Integrate the remote changes (e.g.
      hint: 'git pull ...') before pushing again.
      hint: See the 'Note about fast-forwards' in 'git push --help' for details.
      
      Tofu@Tofu-H170W10 MINGW64 ~/git/luci/applications/luci-app-adblock/po (tool-test)
      $ git push -f origin --all
      Counting objects: 9, done.
      Delta compression using up to 8 threads.
      Compressing objects: 100% (7/7), done.
      Writing objects: 100% (9/9), 1.40 KiB | 0 bytes/s, done.
      Total 9 (delta 3), reused 1 (delta 0)
      remote: Resolving deltas: 100% (3/3), completed with 2 local objects.
      To https://github.com/musashino-build/luci.git
       + e7ad4b4...5325cb2 tool-test -> tool-test (forced update)
      
      Tofu@Tofu-H170W10 MINGW64 ~/git/luci/applications/luci-app-adblock/po (tool-test)
      $
      

  • テンプレート(.pot)が存在しない場合の手順

    luci-app-(App名)/po/ja/(App名).po
    

    が存在せず、また

    luci-app-(App名)/po/templates/(App名).pot
    

    も存在しない場合、まずテンプレートを作成してから翻訳を行う。

    • 準備

      ツールは前述のとおりWindows環境では動作しないため、Linux環境(WSL)を使用する必要がある。
      WSLを起動し、上記 “準備” の項目のGitによるcloneまで行い、また、作業用ブランチも切る。

    • ツールを実行

      LuCI側で用意されているツールを実行し、テンプレートファイルを作成する。
      テンプレートを作成するアプリケーションのディレクトリ以下に po/templates/ ディレクトリを作成した後、WSL上にてLuCIの一番上位のディレクトリで以下のコマンドを実行する。

      ./build/i18n-scan.pl applications/luci-app-(対象App名) > applications/luci-app-(対象App名)/po/templates/(App名).pot
      

      この “i18n-scan.pl” ツールは、最初の引数で指定されたアプリケーション内のソースコードをスキャンして翻訳するよう指定された(translate, translatef関数が付けられている)文字列を探し出し、出力することができる。
      上記コマンドでは “>” を付けているため、その後に指定されたファイルに対して出力された内容が書き込まれる。

      実行例(luci-app-adblock):

      tofu@TOFU-H170W10:~/openwrt/luci$ mkdir -p applications/luci-app-adblock/po/templates
      tofu@TOFU-H170W10:~/openwrt/luci$ ls -al applications/luci-app-adblock/
      合計 12
      drwxrwxrwx 2 tofu tofu   0  1月 24 18:41 .
      drwxrwxrwx 2 tofu tofu   0  1月 24 18:26 ..
      -rw-rw-rw- 1 tofu tofu 292  1月 24 18:26 Makefile
      drwxrwxrwx 2 tofu tofu   0  1月 24 18:26 luasrc
      drwxrwxrwx 2 tofu tofu   0  1月 24 18:41 po
      drwxrwxrwx 2 tofu tofu   0  1月 24 18:26 root
      tofu@TOFU-H170W10:~/openwrt/luci$ ./build/i18n-scan.pl applications/luci-app-adblock > applications/luci-app-adblock/po/templates/adblock.pot
      tofu@TOFU-H170W10:~/openwrt/luci$ ls -al applications/luci-app-adblock/po/templates/
      合計 4
      drwxrwxrwx 2 tofu tofu    0  1月 24 18:42 .
      drwxrwxrwx 2 tofu tofu    0  1月 24 18:41 ..
      -rw-rw-rw- 1 tofu tofu 1199  1月 24 18:42 adblock.pot
      tofu@TOFU-H170W10:~/openwrt/luci$
      

      luci-app-adblockは既にテンプレートと日本語訳が存在するが、今回例として提示するため、一旦全て削除した。
      この “i18n-scan.pl” ツールは、テンプレートが作成された後LuCIのソースコード自体に変更が入り、コード中で翻訳対象として指定された文字列が変更 / 追加された場合に、テンプレートを更新する際にも用いる。
      テンプレートの更新と、それに従って翻訳する言語のpoファイルを更新する方法については、別記事で書く。

    • フォークに変更を適用

      テンプレートを作成したら、今度はWindows上で作業するために一旦GitHubの自分のフォークに対して、作業環境での変更を適用する。
      Gitのaddコマンドを使用して変更した内容を含ませ、

      git add ./
      

      commitコマンドで変更内容を確定する。

      git commit -m "hoge"
      

      このコミットは後でWindows環境に戻った際に一旦取り消すため、コミットメッセージは適当で構わない。
      次に、pushコマンドでフォークに対して変更を押し出す。

      git push origin --all
      

      以上で、自分のフォークリポジトリにWSLで作業した変更内容が適用される。

      実行例:

      tofu@TOFU-H170W10:~/openwrt/luci$ git add ./
      tofu@TOFU-H170W10:~/openwrt/luci$ git commit -m "test"
      [tool-test e7ad4b4] test
       1 file changed, 70 insertions(+)
       create mode 100644 applications/luci-app-adblock/po/templates/adblock.pot
      tofu@TOFU-H170W10:~/openwrt/luci$ git push origin --all
      Username for 'https://github.com': (GitHubユーザー名)
      Password for 'https://(GitHubユーザー名)@github.com': (GitHubパスワード, 表示されない)
      Counting objects: 27, done.
      Delta compression using up to 8 threads.
      Compressing objects: 100% (4/4), done.
      Writing objects: 100% (5/5), 496 bytes | 0 bytes/s, done.
      Total 5 (delta 2), reused 0 (delta 0)
      remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
      To https://github.com/musashino-build/luci.git
         d385688..e7ad4b4  tool-test -> tool-test
      tofu@TOFU-H170W10:~/openwrt/luci$
      

    • Windows上に変更を引き出す
      GitHub上に適用した変更を、Windows上の作業環境に引き出す。既に作業用ブランチを作っていた場合は、一旦削除する。
      Windows上のGit環境で、pullコマンドを実行する。

      git pull origin -a
      

      すると、WSLで作成した作業用ブランチがWindows上のGit環境にも反映されるので、checkoutコマンドで作業用ブランチに移動する。

      実行例:

      Tofu@Tofu-H170W10 MINGW64 ~/git/luci (master)
      $ git pull origin -a
      remote: Counting objects: 9, done.
      remote: Compressing objects: 100% (8/8), done.
      remote: Total 9 (delta 2), reused 0 (delta 0), pack-reused 0
      Unpacking objects: 100% (9/9), done.
      From https://github.com/musashino-build/luci
       * [new branch]      tool-test  -> origin/tool-test
      Already up-to-date.
      
      Tofu@Tofu-H170W10 MINGW64 ~/git/luci (master)
      $ git checkout tool-test
      Branch tool-test set up to track remote branch tool-test from origin.
      Switched to a new branch 'tool-test'
      
      Tofu@Tofu-H170W10 MINGW64 ~/git/luci (tool-test)
      $
      

    • コミットを一旦取り消す

      必要以上にコミットを増やすべきではなく、日本語の翻訳によるコミットとまとめるため一旦WSL上で行った作業のコミットを取り消す。

      git reset --soft HEAD^
      

      “–soft” という引数を使用することで、変更内容を維持しつつコミットを取り消す(”–hard” では変更内容も削除される)。

      以上まで完了したら、再度 poファイルを編集(翻訳)する に戻り、そこからの手順を行う。


PRの流れ

フォーク元のLuCIリポジトリに対してPull Request (PR)を出し、マージされるまでの流れ。

リポジトリを比較する

実際にPRを出す前に、一旦自分のフォークリポジトリとフォーク元のLuCIリポジトリを比較し、変更点を確認する。

GitHubで自分のフォークリポジトリのページを開き、”Branch: master” となっているドロップダウンリストから翻訳作業を行ったブランチを選択する。その後、”Clone or download” という緑色のボタンの下にある “Compare” リンクを開く。

変更内容を確認し、問題なければPRを作成する。

PRを作成する

リポジトリの比較ページ内にある “Create pull request” ボタンを押下し、PR作成画面に移る。
この時、作業用ブランチに含まれるコミットが1つのみの場合は、コミットのsubject(主題)とメッセージがPRにもそのまま反映される。
反映された内容は、特に変更しなくてもOK。
コミットが2つ以上含まれる場合はブランチ名がsubjectに入り、PRのコメントには何も入力されていない状態となる。この時は、主となるコミットの内容をsubjectとPRコメントに書き写すか、もしくは自分で書く。
特に大きい変更でなかった場合も、PRコメントはコミットメッセージ同様に何かしら書いたほうが良い(たぶん)。

PRのsubjectとコメントの内容を確認し、コメント入力欄右下の “Create pull request” を押下するとPull Request (PR)が作成される。

マージ(または修正の指摘)

PRを作成してしばらくすると、LuCIの翻訳関連を担当するメンテナが内容を確認し、マージを行うか、もしくは内容に不備がある場合、その点の指摘と修正依頼が英語で行われる。
何らかの指摘が行われた場合、その指摘に従ってコミットまたはそれに含まれる内容を修正し、再度コミットするなどした後PRのコメントを追加してメンテナに確認を依頼する。
特に指摘など無くマージされた場合、それで完了となる。

後片付け

PRが通過すると、LuCIのmasterブランチへのマージが行われ変更が取り込まれるため、自分のフォークリポジトリの作業ブランチはこの時点で不要となる。
PRが通過すると、PRページの時系列の最後に作業用ブランチの削除ボタンが出現するため、そこからGitHub側の作業用ブランチを削除する。
その後、作業環境内にある作業用ブランチも削除する。

git branch -D (作業ブランチ名)

以上で、1回の翻訳作業が完了。記事が長くなるほど文字量が多くなっていますが、ある程度繰り返して慣れてくるとそんなに時間はかかりません。
不安な時は、LuCIのコミットログやclose済みのPRなど眺めてみましょう。色々ヒントがあります(ぶっちゃけ、筆者自身もガイドラインとPR流し読んだ程度でトライしてみた)。
各種ツッコミお待ちしてます。

広告

コメントを残す

以下に詳細を記入するか、アイコンをクリックしてログインしてください。

WordPress.com ロゴ

WordPress.com アカウントを使ってコメントしています。 ログアウト / 変更 )

Twitter 画像

Twitter アカウントを使ってコメントしています。 ログアウト / 変更 )

Facebook の写真

Facebook アカウントを使ってコメントしています。 ログアウト / 変更 )

Google+ フォト

Google+ アカウントを使ってコメントしています。 ログアウト / 変更 )

%s と連携中