Skip to content

Latest commit

 

History

History
167 lines (111 loc) · 9.41 KB

CONTRIBUTING.md

File metadata and controls

167 lines (111 loc) · 9.41 KB
Raw

Contribution Guide

このリポジトリへのコントリビュート (貢献) 方法についてのガイドです。

注意: 翻訳に参加したい場合はこの文章を必ず一読してください。

このリポジトリについて

このリポジトリの構造は以下のようになっています。

  • i18n/: OmegaTのプロジェクトが格納されたディレクトリ
  • locale/: 翻訳元/翻訳後のファイルが格納されたディレクトリ
    • en/: 翻訳元のディレクトリ
    • ja/: 翻訳後のディレクトリ

また、en/ディレクトリとja/ディレクトリにはそれぞれ、次のようなディレクトリがあります。

注意: これらのディレクトリにあるファイルに対して、原則として直接の編集は行なわないでください。 このリポジトリのほとんどのファイルはOmegaTやmakeなどのツール・コマンドを介して更新されています。

このリポジトリのクローン

このリポジトリはgitのサブモジュールを使っています。 なので--recursiveオプションをつけてクローンすることをオススメします。

$ git clone --recursive https://github.com/crystal-jp/ja.crystal-lang.org
$ cd ja.crystal-lang.org

もし--recursiveオプションをつけ忘れた場合はgit submodule update --initとしてもサブモジュールを取得できます。

ローカル環境でのプレビュー方法

crystal-book

静的サイトジェネレータとしてGitBookを利用しています。 GitBookはMarkdownでドキュメントを記述できるツールです。詳細はGitBookのドキュメントを確認してください。

GitBookを利用するにはCLIツールをインストールする必要があります。 npmコマンドが使える環境で、以下のコマンドを実行してください。

$ npm install -g gitbook-cli

これでgitbookコマンドが利用できるようになります。

(npm install -gをするのが嫌な場合はインストールをせず、gitbookコマンドの代わりにnpx -p gitbook-cli gitbookとすることもできます。)

次にGitBookのプラグイン等をインストールします。

$ cd locale/ja/crystal-book # ディレクトリの移動
$ gitbook install

最後に、プレビュー用のサーバーを起動します。 最初にビルドをするので、サーバーが立ち上がるまで少し時間がかかるのに注意してください。

$ gitbook serve

Serving book on http://localhost:4000と出たらブラウザでhttp://localhost:4000/を開くとプレビューが見れるはずです。 一度gitbook serveを実行すると、locale/ja/crysta-book以下のファイルが更新される度に再度ビルドが行なわれ、自動で内容が更新されるようになっています。

以降、依存関係等の更新が無ければ、最後のgitbook serveを実行するだけでプレビューができます。

(crystal-bookのREADME.mdにはdocker-composeを利用する方法も説明されていますが、この方法はファイルを更新したときに安定しないので個人的にはオススメしません)

crystal-website

静的サイトジェネレータとしてJekyllを利用しています。 JekyllはRubyで書かれた静的サイトジェネレータです。詳細は公式サイトを確認してください。

こちらはプレビューにdocker-composeを使っても問題が起きづらいので、その方法で説明します。 次のコマンドを実行してください。

$ cd locale/ja/crystal-website # ディレクトリの移動
$ docker-compose up

これでしばらく待つとServer address: http://0.0.0.0:4000という表示が出るので、ブラウザでhttp://localhost:4000を開くとプレビューが見れます。 こちらもlocale/ja/crystal-website以下のファイルが更新されると自動で再度をビルドを行います。

翻訳の仕方

OmegaTのセットアップ

翻訳にはOmegaTというソフトウェアを利用しています。 またOmegaTにいくつかのプラグインを導入する必要があります。 その方法を説明していきます。

まずOmegaTをインストールしてください。 筆者はバージョン4.3.2 (6a661c5e0) というバージョンのOmegaTを利用しています。 なるべく、このバージョンに近いOmegaTをインストールしてください。

(Homebrewであればbrew cask install omegatでインストールできます)

次にMarkdownを翻訳するために必要なプラグインであるOkapi Filters Plugin for OmegaTをインストールします。 基本的には「Download and Installation」の内容に従えばよいです。

  1. Okapi Filter Pluginのリリースページからバージョン1.7-1.39のzipファイルをダウンロードしてください。 (okapiFiltersForOmegaT-1.7-1.39-dist.zipという名前です)
  2. ダウンロードしてきたzipファイルを解凍して、その中にあるjarファイル(okapiFiltersForOmegaT-1.7-1.39.jar)をOmegaTの設定ファイルのあるディレクトリに配置します。 設定ファイルのあるディレクトリはWindowsであれば<OmegaTをインストールしたディレクトリ>/plugins、macOSであれば~/Library/Preferences/OmegaT/pluginsです。

翻訳元ファイルのコピー

重複したファイルをリポジトリに入れることを避けるため、翻訳プロジェクトには翻訳対象のファイルは含まれていません。 次のコマンドを実行して、翻訳元からi18n/sourceディレクトリに翻訳対象のファイルをコピーする必要があります。

$ make i18n/source

このコマンドによってlocale/en以下の翻訳対象のファイルがi18n/sourceディレクトリ以下にコピーされて、OmegaTで開いた際の翻訳対象に含まれるようになります。

ここまで来ればOmegaTでこのプロジェクトを開くことができるはずです。 OmegaTのメニューから「プロジェクト > 開く」でこのリポジトリのi18nディレクトリを指定するか、macOSであればopen -a OmegaT i18nなどと実行して、OmegaTでこのプロジェクトを開いてみてください。

フィルタの設定

次にOmegaTのフィルタを設定します。 これをしないと、翻訳済みの文章が適切に表示されなかったり、訳文ファイルを生成したときに余計な差分が発生してしまう可能性があります。

OmegaTを起動してプロジェクトを開いた状態で「プロジェクト > プロジェクト設定」を選択して、プロジェクト設定ダイアログを表示してください。 そして、その中の「ファイルフィルター」というボタンを押して、フィルタの設定画面を開いて、以下の操作を行なってください。

  1. 「HTML・XHTML」という項目にあるチェックを外します。
  2. 「Markdown files (Okapi)」という項目を選択して、「設定」ボタンをクリック。 出てきた画面で「Use the file parameters file:」にこのプロジェクトのi18n/okapi/okf_markdown@crystal-jp.fprmを選択してください。
  3. 「HTML files (Okapi)」という項目を選択して、「設定」ボタンをクリック。 出てきた画面で「Use the file parameters file:」にこのプロジェクトのi18n/okapi/okf_html@crystal-jp.fprmを選択してください。

以上で設定は完了です。 設定を更新したらプロジェクトを再読み込みするよう促されるはずなので、ここで再読み込みを必ず行なってください。

これでOmegaTでの翻訳をはじめられるはずです。 OmegaTの具体的な使い方は各自調べてください。

Pull Request

あるファイルに対して翻訳が完了したら、OmegaTでプロジェクトを保存したのち、「プロジェクト > 訳文ファイルを生成」を実行してください。 これを実行することで、i18n/targetに翻訳結果のファイルが生成されます。

そして、次のコマンドを実行することで、翻訳結果のファイルがlocale/ja以下にコピーされます。

$ make locale/ja

この後は、通常Gitを使うようにgit switch、git add、git commitして、自分のForkしたリポジトリに向かってgit pushしてください。

$ git switch -c feat/translate-xxx
$ git add i18n locale/ja/
$ git commit -m "feat: translate xxx"
$ git push fork feat/translate-xxx

その後、GitHubでPull Requestを作成してください。