# コミュニティ翻訳進め方案
## 前提：
以下ではgit/GithubおよびOmegaTを活用することを前提としたコラボ翻訳の進め方の案を記載している。他のやり方も当然考えられる。
## 1. 全体イメージ
- **ポイント**
- 共有レポジトリは翻訳対象ドキュメント（OSS開発コミュニティで共有：下記青色）と翻訳メモリ用（翻訳プロジェクトで共有：下記橙色）の２つ存在する
- あるドキュメントについての翻訳主担当者（メイントランスレータ）は、この２つについてコントリビュートする（＝Pull requestを出す）
- 翻訳主担当者はアップストリームのリモートレポジトリをforkして自分のローカルレポジトリで作業する
- この際対象ドキュメントごとにfeature branchを切って作業する
- OmegaTでの翻訳作業後オンラインリアルタイムレビューを実施する
- 修正内容をOmegaTに反映し、アップストリームへPRを出す
- **イメージ図**
- 以下のとおり（順番も示したかったが見づらくなるなるため割愛する）
## 2. 作業にあたっての前提条件
### [スキルまわり]
**＜メイントランスレータ＞** ←必須ではない。熱意と志こそもっとも大事。
* 英語読解力と日本語表現力
* Git関連スキル
* Github関連スキル
* OmegaT関連スキル
* ねばりづよさと辛抱強さ、そして少々のリーダーシップと少々のユーモアセンス（笑）
**＜レビュワー＞**
* 英語読解力と日本語表現力
### [アカウントなどの準備]
**＜メイントランスレータ＞**
* Githubアカウント
* コミュニティでのCLA(Contributor License Agreement) ※必要な場合
* 機械学習APIのためのアカウント（GCPアカウントなど）
* チャットツールアカウント（Slackなど）
**＜レビュワー＞**
* Githubなどのアカウント(hackmdなどのログインのため)
* チャットツールアカウント（Slackなど）
### [ツールなどの準備]
**＜メイントランスレータ＞**
* OmegaT
* Gitクライアント
## 3. 作業の流れ
### (0) 事前
- 翻訳対象ドキュメントのメタ情報整理
以下のような情報を整理していく
→コラボ翻訳の円滑化、その評価などに必要な情報をWikiやHackMDなどで関係者が共有できるようにしておく。
- 原文リンク
原文リンクを共有し、コンテンツの中身などがわかるようにしておく。
- ワードカウント
どれぐらいのワードカウントかを事前に把握し、その作業を共有する。
（参考：Ubuntu Linux でのワードカウントスクリプト→HTMLタグを削除し得してwcコマンドでワードカウントする）
``` $sed "s/<[^>]*>//g" $2 | wc -w```
*** 未記入 ***
（対象決定、メンバ調整、日程調整、翻訳ルール/ガイドライン、用語集など。開発コミュニティでのルールなども確認する）
### (1) アップストリームリポジトリからのfork
右上のforkボタンを押して自分のリポジトリにforkする。
*** 未記入 ***
### (2) ローカルレポジトリへのclone
- Github上でのclone（略→検索）
- コマンドライン（例:TODO Groupからのクローン）
- ローカルフォルダを作成しクローンを作成する
```
~/git$ mkdir TODO_trans
~/git$ cd TODO_trans/
~/git/TODO_trans$ git clone https://github.com/maabou512/todogroup.github.io
~/git/TODO_trans/todogroup.github.io$ ls
LICENSE README.md assets content i18n netlify.toml Makefile archetypes config.yaml data layouts static
```
### (3) 翻訳作業の実施
#### a: 開発コミュニティでの対応
- issueを発行し翻訳担当になることを宣言する
#### b: 翻訳プロジェクトでの対応
コラボレーション翻訳においては、以下のような要件を満たすことが好ましい
1. 翻訳作業の最大限の自動化、効率化
2. 多彩なファイル形式への対応
3. 対訳の出力（HackMDでのリアルタイムレビューでは必須）
基本的に1のためにOmegaTを用い、3のためにOkapi Rainbowを用いる。なお1についてHTML形式のファイルにOmegaTのパーシングが脆弱であることから、Okapi Rainbowを用いるケースもある。[参考URL:「OmegaT補助ツールとしてのOkapi Rainbow」](https://momdo.hatenadiary.org/entry/20140406/p1)
【XLF 形式ファイルの生成（対訳生成）】
対訳生成をすることが主な目的
1. Okapiでの作業（対訳出力されるXLFファイルを生成する）
こちらを参照：[「OmegaT補助ツールとしてのOkapi Rainbow」](https://momdo.hatenadiary.org/entry/20140406/p1)
2. OmegaTでの機械翻訳（XLFファイルに対し機械翻訳を実施する）
3. 対訳の生成
OmegaT出力ファイルに対し、以下のスクリプトで対訳を生成しHackMDに貼り付けレビューできるようにする
```
#!/bin/bash
tempfile1=$(mktemp)
#echo $tempfile1
sed -e 's/<[^>]*>//g' $1 |sed -e 's/"\/>//g'|sed -e 's/">//g'|sed -e '/^$/d'|sed '1~2s/^/> / '|sed -e '1~1s/$/\n/' > $tempfile1
cat $tempfile1 > $2
```
【スクリプトの解説】
①HMTLタグを削除する（HTMLファイルでなくても）
②不要な空白業を削除する
③対訳形式となるように、英語原文に引用符号（>）を付与
④HackMDで対訳評されるよう改行を挿入
- OmegaT 事前設定
対訳作成を考慮して、行が同じになるようにする
【対訳の設定】
【OmegaTの作業】
- 翻訳ディレクトリの作成②（例：ディレクトリ名「omegat_pj」）
```
~$ mkdir omegat_pj
```
- 作成したディレクトリでOmegaTプロジェクトを作成
- 原文の追加（Github PJ ディレクトリ→OmegaT PJディレクトリの「source」）
*** 未記入 ***
（htmlに対するOkapi Rainbowでの前処理、OmegaTでの機械翻訳、などについて記載
翻訳ルール/ガイドラインなどについてもここで触れる？）
- 機械翻訳の実施
- 対訳作成
$ paste -d '\n' source/file1 file2 >test3
### (4) オンラインレビューの実施
*** 未記入 ***
(hackmdでのレビュー作業について言及。)
### (5) 翻訳結果のアップストリームへの提供
K8S ithubでの作業の流れは以下が参考になる
https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md
※以下はK8sのやり方で記述する
#### a: 開発コミュニティレポジトリでの対応
-
##### a-1. 最初のPull requestを出すまで
- 事前：Git Issueを立てる
- New Isuueをクリック
※ちなみに期限超過なので一度closeしてしまったものを再度openするにはcloseしたissueで一番したで
```/reopen``` とする。
- 新たな翻訳についてはFeature Reqeustとして立てる
- 記入例：
```---------------------------------------------------
**This is a Feature Request**
What would you like to be added
Translation for case study of AppDirect
https://kubernetes.io/case-studies/appdirect/
**Why is this needed**
No translation exists in Japanese.
And this case study is so useful for Japanese readers (not only for developers)
**Comments**
Copy a file from en contents to content/ja/case-studies/appdirect/index.html and content/ja/case-studies/appdirect_featured_logo.png and translate it into Japanese.
/language ja
/assign
---------------------------------------------------
````
※意味
``` /language ja``` *ラベル。検索クエリで皆が使う。日本語翻訳であることを示す*
```/assign``` *自分がやるぞ宣言 = /assign @(自分）*
- 翻訳する
（前述の流れに沿って翻訳する）
- upstreamのブランチ名を定義しておく
```$ git remote add <upstreamの名称> <url(https://github.com/kubernetes/website.git)>```
※(名前変える場合は）
``` $git remote rename <old branch> <new branch> ```
例：
```$git remote rename root_branch upstream ```
確認する
```
$ git remote -v
origin https://github.com/<自分のリモートリポジトリ>/website.git (fetch)
origin https://github.com/<自分のリモートリポジトリ>/website.git (push)
upstream https://github.com/kubernetes/website.git (fetch)
upstream https://github.com/kubernetes/website.git (push)
```
- ブランチを作る（Feature branch/Topic branch）
翻訳の場合ならFeature RequestしたのでFeature branchになる。**基本作業はこのブランチでやる**。
- まず確認
```$ git status ```
- ブランチを立てる（Issueとの紐付けで命名）
```$ git checkout -b （iessueとの紐付けブランチ名）```
（例）
```$ git checkout -b issue_15222_appdirect```
- 自分のブランチ音確認
```
$ git branch
issue_14977_chinaunicom
* issue_15222_appdirect
master
```
- 最新版を持ってくるためにまずmasterに移動
```$git checkout master```
- PRを出す前に全体のファイルを最新版にする
```
$git checkout master
$git pull <upstream名> master
```
-- 確認
```$git log```
→日付などをチェックし、最新版になっていることを確認
- 更新するファイルのあるfeature branchに移動（checkout）する
```$git checkout (feature branch名)```
- git logで更新を確認
```$git log```
- Updateされたmasterブランチの内容をFeature Branchに反映する(rebase)
``` $git rebase master ```
- git logで確認
``` $git log```
- 修正内容の確認
```$git status ```
``` $git diff ```
- commitするための作業:編集内容をstarging areaに加えることでcommit対象にする
``` $git add (修正したファイル名）```
- commitする
``` $git commit ```
→ ここでメッセージを入力。
考え方：1行目がタイトル、簡潔に短く※ドットで終わらせないこと
2行目が空行
3行目移行に内容。このコミットが何をしているか
（2行目移行はなくてもよい）
デフォルトのコメント行は消しても消さなくてもよい
例）
ja-trans: content/ja/case-studies/chinaunicom
- 自分のリモートレポジトリにpushする (自分のリモートレポジトリが「origin」の場合。git remote -vで事前に確認できる)
``` git push origin （feature branch名）```
- Pull Requestの発出
Githubサイトにて自分のレポジトリを確認しPull Requestボタンを押す。
以下のようにかく。
> Translation for case study of AppDirect
> https://kubernetes.io/case-studies/appdirect/
>
> Fixes #15222
>
- Pull Requestの内容の確認
自分が出したい内容についてファイルの種類と、数をちゃんと合っているかをスクロールして
確認し、正式発行する
<span style="color:red">※ここで、以前出したPRのcommitの変更内容が混在している重複している現象が発生したので対応策を記載しておく</span>
```
git reset （commitハッシュ） #一旦commitを戻す
git status # commit前の変更されている対象を確認
git add (commitしたいものだけをaddする)
git status # commit対象だけが残ってることを確認
git commit # 再度commit
git push -f origin (ブランチ名) #再度push
```
- PR発出後担当者のアサイン先がわかっている場合（k8sではPR発出後botが教えてくれることがある）
/assign @（アサイン先）
以上でPRは終わり。
##### a-2. 修正するとき
PRでレビューコメントがついて修正が必要な場合は、編集して自分のリモートレポジトリまでのpushで修正が反映される。
- Githubでのコメントなどにより修正内容を確認し修正する
-
- PRを出す前に全体のファイルを最新版にする （ここではアップストリーム=「upstream」)
``` $git checkout master ```
``` $git pull root_branch master ```
``` $git log ``` →日付などをチェックし、最新版になっていることを確認
- 更新するファイルのあるfeature branchに移動（checkout）する
``` $git checkout (feature branch名) ```
- git logで確認
``` $git log ```
- Updateされたmasterブランチの内容をFeature Branchに反映する(rebase)
``` $git rebase master ```
- git logで確認
``` $git log```
- 修正内容の確認
```$git status ```
``` $git diff ```
- commitするための作業:編集内容をstarging areaに加えることでcommit対象にする
``` $git add (修正したファイル名）```
- commitする
``` $git commit ``` → ここでメッセージを入力。
- 初めてのPull requestのとき：きちんと書く（書き方のポイントなど要補足）
- 一度出したPull Request修正のとき: 適当でいい。dummyとか（あとで消すので）
- ログを確認し、rebaseする
``` $git log ```
``` $git rebase -i (rebaseする基準のcommit hash値) ```
↑修正のときのみ
**【例：修正前1】**
```
pick e210ba910 ja-trans: content/ja/case-studies/chinaunicom
pick 44d72a231 dummy
# Rebase f600acf2b..44d72a231 onto f600acf2b (2 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
**【例：修正後1】**
```
pick e210ba910 ja-trans: content/ja/case-studies/chinaunicom
squash 44d72a231 dummy
# Rebase f600acf2b..44d72a231 onto f600acf2b (2 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
上記修正を保存終了すると更に編集画面になる。
**【例：修正前2】**
``` # This is a combination of 2 commits.
# This is the 1st commit message:
ja-trans: content/ja/case-studies/chinaunicom
# This is the commit message #2:
dummy
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date: Mon Jul 1 18:15:02 2019 +0900
#
# interactive rebase in progress; onto f600acf2b
# Last commands done (2 commands done):
# pick e210ba910 ja-trans: content/ja/case-studies/chinaunicom
# squash 44d72a231 dummy
# No commands remaining.
# You are currently rebasing branch 'issue_14977_chinaunicom' on 'f600acf2b'.
#
# コミット予定の変更点:
# new file: content/ja/case-studies/chinaunicom/chinaunicom_featured_logo.png
# new file: content/ja/case-studies/chinaunicom/index.html
#
# 追跡されていないファイル:
# content/ja/case-studies/index-chinaunicom
```
**【例：修正後2】** コメントアウト行を残しても良いが、不要なものを削除する。特にgitでは一行目には意味があるので、コメント行にしないように配慮する
```
ja-trans: content/ja/case-studies/chinaunicom
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date: Mon Jul 1 18:15:02 2019 +0900
#
# interactive rebase in progress; onto f600acf2b
# Last commands done (2 commands done):
# pick e210ba910 ja-trans: content/ja/case-studies/chinaunicom
# squash 44d72a231 dummy
# No commands remaining.
# You are currently rebasing branch 'issue_14977_chinaunicom' on 'f600acf2b'.
#
# コミット予定の変更点:
# new file: content/ja/case-studies/chinaunicom/chinaunicom_featured_logo.png
# new file: content/ja/case-studies/chinaunicom/index.html
#
# 追跡されていないファイル:
# content/ja/case-studies/index-chinaunicom
```
- 再度ログを確認
``` $git log ``` →（何をチェックするか要記載）
- 自分のリモートレポジトリにpushする (自分のリモートレポジトリが「origin」の場合。git remote -vで事前に確認できる)
``` git push origin （feature branch名）```
※修正の場合は必ずエラー出るので-fを実施する
``` $git push origin -f （feature branch名） ```
- 初めてのPull Requestの場合は、githubのリモートリポジトリでPull requestボタンを押下する（ここで初めて開発コミュニティに飛ぶ） ※一度出したPull Requestの修正の場合は作業不要。
#### b: 翻訳プロジェクトレポジトリでの対応
*** 未記入 ***
### (6) アップストリームでの状況チェック、対応
#### a: 開発コミュニティレポジトリでの対応
(確認作業やコミュニケーションなど)
#### b: 翻訳プロジェクトレポジトリでの対応
(確認作業やコミュニケーションなど)
Sign in with Wallet
Connect another wallet