ハンドブックをまるまる翻訳する仕組みを考える

[miya0001]

No description provided.

[miya0001]

要件

• 翻訳されていない場合はオリジナルを表示するか、オリジナルへのリンク等を表示すること。
• オリジナルに更新があった場合にそのことをキャッチできること。あと、そのページの翻訳がオリジナルに対して古いことを表示できること。
• できれば無料で使えるインフラが良い。もしくはWordPress.orgのMetaチームに頼む。
• 不特定多数が参加しやすいこと。

[miya0001]

個人的に考えた仕様は以下

• REST-API経由でコンテンツをまるごとコピー。これは定期的に行う。
• コンテンツはまるごとマークダウンに変換して、オリジナルのslugをファイル名として保存してgitで管理する。
• タグをつけてgitで差分を取得できるようにする。
• ここまではスクリプトで行う。
• 別リポジトリで上のリポジトリをフォークしてマークダウンを翻訳。
• これをjekyllでサイトとして表示。
• jekyllのテンプレにjsを仕込んで、オリジナルの最終更新日と翻訳ファイルの日付を比較すれば、その翻訳が最新の記事をベースにしてないことはキャッチできそう。ただし、翻訳途中であることはこれだけだとキャッチできない。マージするときに翻訳が完了してることを条件にする？
• 未翻訳の場合はそのマークダウンがないので、オリジナルからREST API経由でコンテンツを表示できるきがする。
• 翻訳後にオリジナルの更新があった場合の差分はGitHubのAPIで取れる。

[miya0001]

以下communityのハンドブックのREST API

https://make.wordpress.org/community/wp-json/wp/v2/pages

[miya0001]

あるページを翻訳し始めて、それが終わるまでにそのページのオリジナルが更新されたことをキャッチできへんかなと思ったけど、jekyll用のメタデータをマークダウンに変換するときにつけとけばいいかも。例えばオリジナルの記事の最終更新日とか。

[miya0001]

翻訳するときはフォークしたらあかん。

[miya0001]

メニューがカスタムメニューなのか固定ページをそのまま使ってるのか、チームによって違ったりするのか聞かないかんな。

[ixkaito]

下層のハンドブックページ (例: https://make.wordpress.org/community/handbook/meetup-organizer/welcome/) はカスタム投稿タイプみたいなので、API 提供されてないかも。

[ixkaito]

取り急ぎ簡単な翻訳の仕組みを考えました。

1. 原文の英語マークダウンを例えば en ブランチにコミットして、ここから始める
2. それを ja ブランチとかにチェックアウトして、ここで翻訳する
3. 翻訳方法は原文をマークダウンのコメント機能 [](原文) を使ってコメントアウトし、それに対する訳をつける
4. 原文に変更があった場合は en ブランチにコミットし、ja ブランチで rebase en する
   1. ここではかならずコンフリクトが発生しますが、解消するのはそんなに難しくないです。この作業はコミッターがやればいいと思います。

[miya0001]

ハンドブックのREST-APIにバグ見つけたので、できる範囲で相談します。

[ixkaito]

4. rebase en じゃなくて普通に merge en ＋コンフリクト解消でよさそう。

[miminari]

翻訳方法は原文をマークダウンのコメント機能 を使ってコメントアウトし、それに対する訳をつける

https://github.com/miminari/wp_meetup_handbook_copy/blob/translate/responding-to-code-of-conduct-violations.md

今やってみてるんですが、これって、原文は行ずつとかでしょうか？あと何故か[](原文)が効かないです。HTMLの<!-- -->は効くのですが…。

[ixkaito]

はい。マークダウンでは行、HTML でいうと p 単位がいいかなと思います。

あと何故かが効かないです。HTMLのは効くのですが…。

GitHub で [](コメント) 効かないかもしれません。<!-- コメント --> でいいと思います。https://github.com/jawordpressorg/community-handbook でサンプル作りますので少々お待ち下さい。

[miya0001]

翻訳後のオリジナルの更新をREST-APIでトラッキングできる気がするのでチケット立てた。
https://meta.trac.wordpress.org/ticket/3679

[ixkaito]

ありがとうございます！

[miya0001]

metaチームのミーティングで催促した。
https://wordpress.slack.com/archives/C02QB8GMM/p1530135569000405

[mirucon]

みやさんのチケットマージされて、Handbook が REST API 経由でアクセスできるようになってたので、お試し程度にテーマレビューの日本語訳のやつで原文追跡できるようにしてみました https://github.com/mirucon/required-ja

原文を追跡するだけなら簡単にできそうなんですが、それを訳の中のコメントアウトされてる方に反映させる方法させる方法についてはもう少し考えてみないといけなさそうですね…。

[miya0001]

@mirucon おー、ナイスですね。僕もTravis CIでREST-APIのレスポンスをキャッシュしてゴニョゴニョというイメージで考えていました。

あとは、翻訳したマークダウンファイルに翻訳の日付及びスラッグをメタデータとして保存しておくとJSで「この記事の翻訳はオリジナルに対して古い可能性があります。」と表示できるのではないかなと考えています。

メタデータの保存の仕方は以下のような感じ。

---
layout: post
title:  "Welcome to Jekyll!"
date:   2015-11-17 16:16:01 -0600
categories: jekyll update
---

You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `bundle exec jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.

To add new posts, simply add a file in the `_posts` directory that follows the convention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.

[miya0001]

---
layout: post
title:  "Welcome to Jekyll!"
date:   2015-11-17 16:16:01 -0600
categories: jekyll update
---

の部分がメタデータで、YAMLフォーマットが使えた気がします。

[miya0001]

この場合、オリジナルの本文のどの行が古いのかを取得するところまでは解決できていないのですが、現時点ではあとまわしでいいかなと思っています。
（翻訳をしている人たちの手を止めたくない ＆ あとでまとめて解決できる気がしてる。）

[miya0001]

@mirucon 以下どう思いますか？

1. Nodeベースのコマンドをつくる

• このコマンドを Travis CI で npm install -g でインストールして実行する。
• wp-json/v2/wp/handbook をまるごと全部掘ってメニュー用のJSONを生成する。（X-WP-TotalPagesヘッダーの中身とかちゃんと判別してね♡）
• 生成したJSONはgh-pagesブランチの /api/v1 っていうディレクトリに放り込む

メニュー用のJSONには各ハンドブックのページを以下のようなスキーマで配列で放り込む感じ。

• 翻訳元ページのスラッグ
• 翻訳元ページの最終更新日
• 翻訳元ページのURL
• 翻訳元ページのmenu_order
• 翻訳元ページの親ページID

このJSONをAjaxで読み込んで未翻訳のページや翻訳が古いページを検出する感じ。
gh-pages に JSON をコミットすると自動的に CORS も許可されるので翻訳プロジェクトとは別にコマンドもAPIもメンテできます。
コマンドは単独のリポジトリでメンテして npm publish するなりすれば、翻訳プロジェクトはそれをインストールして実行すればいいので使いまわししやすいんじゃないかと。あと今はまだ読み切れていない未知のユースケースにもまとめて対応できると思います。
あとJSONを人力でコミットしないでもよくなるので、TravisのCronを使って自動実行もやりやすい気がします。
WP側のREST-APIで記事が多くても、コンテンツがないぶん軽くなるので、一つのAPIにまとめちゃえばいいかなと。

[mirucon]

@miya0001 素晴らしいと思います ! Handbook 自体かなり数あるので、流用できるようにするのは良い仕組みですねー

[miya0001]

@mirucon ではまかせた！

[mirucon]

@miya0001 丸投げかよ ! w まあやるけども

[mirucon]

@miya0001 ひとまず雰囲気掴める程度に handbook <チーム名> で特定の handbook の JSON 吐き出すスクリプト書きました。https://github.com/mirucon/handbook-tracker
多分一発で全部のチームのハンドブック取れるやつがあったほうがいいとは思うんですが、マルチサイトになってるサイト (make.w.org ってマルチサイトですよね ? ) 全部の slug とってこれるエンドポイントだかってありましたっけ ?
あとチームによっては (community とか) チーム内に2つ以上の handbook 持ってるので、それも含めて一発で全部取ってくる処理をどうするかも考えてみないといけないです。

[miya0001]

ありがとうございます！
ざっと見ただけですが、いい感じだと思います。週末あたりにちゃんと見てみます。

多分一発で全部のチームのハンドブック取れるやつがあったほうがいいとは思うんですが、マルチサイトになってるサイト (make.w.org ってマルチサイトですよね ? ) 全部の slug とってこれるエンドポイントだかってありましたっけ ?

すべての翻訳をするわけではないので、一発で全部取る必要はないかなと思いますので今の路線で行きましょう。

マルチサイトになってるサイト (make.w.org ってマルチサイトですよね ? ) 全部の slug とってこれるエンドポイントだかってありましたっけ ?

デフォルトではマルチサイト用のAPIは特にないのですが、子サイトのURLがわかればオートディスカバリをつかって、どんなAPIがあるかをとることはできます。
今は決め打ちでやってますが、サイトのURLからオートディスカバリを使ってhandbookのAPIを取得するようにするとプラグインでAPIのルートをカスタマイズしていてもそれを検出することができます。

$ curl --dump-header - https://make.wordpress.org/community/
HTTP/2 200 
server: nginx
date: Wed, 04 Jul 2018 08:21:11 GMT
content-type: text/html; charset=utf-8
vary: Accept-Encoding
link: <https://make.wordpress.org/community/wp-json/>; rel="https://api.w.org/"
link: <https://wp.me/2U65r>; rel=shortlink

まあまとめて取る場合はこういうことも考えないといけないですが、今回のユースケースではひとつずつ取ればいいんじゃないかと思います。

[mirucon]

@miya0001 とりあえずコマンドの方は大丈夫だと思うので、これ前に進めましょう。
生成した JSON をどういう風に使うのかあんま読めてないんですが、JSON ファイル上にある URL をすべて読み込んでデータ取って、それを原文ブランチ (https://github.com/jawordpressorg/community-handbook/ であれば en ブランチ) との比較という感じですかね ? あ、でもそうすると未翻訳のページは取れないですよね、そのへんどう考えてるか教えてください。

[miya0001]

1. 翻訳版のハンドブックのメニューをREST-APIからとってきたJSONをベースに生成。
2. 来訪者がそのメニューから特定のページに移動。
3. そのページが存在していれば（翻訳済みであれば）表示される。
4. そのページが存在しなければ、Jekyllの404のテンプレに仕込んだJSでオリジナルへのリンクを表示したり翻訳を促すメッセージを表示したりする

って感じかなと。

[mirucon]

ああなるほど、なんとなく掴めました。そうするとメニューを生成する部分はどうやって管理するかって決めてますか ? GitHub Pages あたりでデプロイする感じなのかなと思いますが、テンプレ用意してそれをレポジトリ毎にインストールして使ってもらう感じですかね。

[miya0001]

Travis CIのCronでハンドブックのREST-APIを蹴っ飛ばしてそれをもとに上でコメントしたメニュー用のJSONを生成してそれでメニューを表示する感じかな。
#24 (comment)

[mirucon]

あ、ええっと、聞きたいのはメニューを表示する部分の Jekyll とかのテンプレートをどういう風にするのかです。その部分はどの Handbook であっても共通の部分なので、コマンドと同じようにそれ単体で GitHub のレポジトリに置いてテンプレートを管理するという認識であってますか ? それを各 Handbook 翻訳のレポジトリの gh-pages ブランチにクローンしてコマンドで生成された JSON ファイルを元にメニューを生成、という感じなのかなと。Jekyll を使ったことがないのでテンプレート部分がいまいち想像つきにくいのです。

[miya0001]

Jekyllのテーマを配るイメージで行けるかなーと思ってるのですが、やってみないとわかんないですね。
今月いっぱい忙しくなってしまったので、手が空いたときに僕も挑戦してみます。

[mirucon]

ちなみに Jekyll にこだわる意味ってありますか ? VuePress だったら僕やりたいなあと思うんですけど、Jekyll のがベターですかね。

あ、でも VuePress だとテーマ配れるかわからないや、ちょい検証します

[torounit]

@mirucon Jekyll だと Github Pages でやる場合は、勝手にビルドとかしてくれるので楽ってのはあります。ただ、どうせ API から取ってきて CI 回して･･･ってことをやるのであればどっちにしろビルドは必要な気がするのでやりやすいもので良いのかなと。

[miya0001]

どっちにしろTravisに依存するのでなんでもいいんじゃないですかね。Jekyllにこだわらないですよ。

[mirucon]

了解です、なんか適当に良いのないかちょっと見てみます

[mirucon]

VuePress 試してみましたが、サイドバーを多重ネスト構造にできないのでだめでした。静的サイトジェネレータで有名なのって何があるのかあんまりわからない…。

[miya0001]

じゃあ、すなおにJekyllにしましょうか。とりあえず適当なテーマで意図通りのことができるか試してみます。

[ixkaito]

ハンドブックの翻訳って結局 GitHub Pages で行くんですか？

[miya0001]

とりあえずそういう仕組を作ろうかなーと。