英語のドキュメントを翻訳していると、翻訳が古くなることがある。本家ドキュメントが GitHub で管理されていれば、本家が更新されて翻訳が古くなったときに、差分だけを翻訳し直して最新に追従するといったことができる。そうするためには、翻訳ドキュメントの中に本家ドキュメントのコミットハッシュ値を書き残しておけばよい。本家が更新されたら、最新のコミットと、翻訳が参照しているコミットを見比べる。
このやり方を応用して、翻訳ドキュメントが本家の最新コミットに追従しているかどうかをひと目でわかるようにしたのが、このバッジである。
バッジには本家ドキュメントのコミットハッシュ値が含まれていて、その値が本家の最新のコミットハッシュ値を一致していれば up to date と表示され、一致していなければ out of date と表示される。
https://shields.io のカスタム JSON エンドポイントを利用している。バッジの表示までに 2 ステップあって、まず JSON を返す URL を組み立てて、つぎにその URL を shields.io のエンドポイントにわたす。
GitHub 上にある本家ドキュメントを指定するために、JSON エンドポイントに以下の情報を与える。
- リポジトリ名
- ブランチ (またはタグ) 名
- コミットのハッシュ値
- ドキュメントのファイルパス
これらを JSON エンドポイントにクエリ文字列で与える。
https://gezf7g7pd5.execute-api.ap-northeast-1.amazonaws.com/default/source_up_to_date?owner=${OWNER}&repos=${REPOS}&ref=${REF}&path=${PATH}&commit_hash=${COMMIT_HASH}
${OWNER},${REPOS}... リポジトリの所有者、リポジトリ名${REF}... ブランチ (またはタグ) 名${PATH}... ドキュメントのファイルパス${COMMIT_HASH}... コミットのハッシュ値
たとえば、
- リポジトリ: FujiHaruka/test-repo-for-up-to-date-badge
- ブランチ: master
- ファイル: DOC.md
- コミット: 9c747933ce75a996a555cda02bfb376b1b357d71
であれば、以下のようになる。
https://gezf7g7pd5.execute-api.ap-northeast-1.amazonaws.com/default/source_up_to_date?owner=FujiHaruka&repos=test-repo-for-up-to-date-badge&ref=master&path=DOC.md&commit_hash=9c747933ce75a996a555cda02bfb376b1b357d71
実際に curl でリクエストを送ってみると JSON が返ってくる。
$ curl "https://gezf7g7pd5.execute-api.ap-northeast-1.amazonaws.com/default/source_up_to_date?owner=FujiHaruka&repos=test-repo-for-up-to-date-badge&ref=master&path=DOC.md&commit_hash=9c747933ce75a996a555cda02bfb376b1b357d71"
{"schemaVersion":1,"label":"translation","message":"up to date","color":"brightgreen","isError":false}
(1) で作った URL を shields.io のエンドポイントの渡す。クエリ文字列で渡すときに URL エンコードする必要がある。(1) の例を使うと、URL 全体としては以下のようになる。
https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgezf7g7pd5.execute-api.ap-northeast-1.amazonaws.com%2Fdefault%2Fsource_up_to_date%3Fowner%3DFujiHaruka%26repos%3Dtest-repo-for-up-to-date-badge%26ref%3Dmaster%26path%3DDOC.md%26commit_hash%3D9c747933ce75a996a555cda02bfb376b1b357d71
あとは、Markdown の画像として表示すればよい。
これを表示すると、
となる。
試しにコミットのハッシュ値を最新でないものに置き換えてみよう。
これを表示すると、
となる。