新しいローカライズ文言管理ツール hoshi を作っています

Dev

これまで担当してきたプロジェクトでは、たびたびローカライズ文言の管理に頭を悩ませることがありました。

もちろん日本語のみ対応すればよいプロジェクトであればソースコードにべた書きというという手もあり、時間がないプロジェクトでは実際にそうしてきましたが、本来ビューにある純粋なリソースであるので、単一言語でも文字列リソースとして管理されるべきだと考えています。

ローカライズ文言管理をプロジェクトに導入しようする際に、スプレッドシートベースの管理などいろいろ試してきましたが、どのプロセスも最終的にしっくりきませんでした。また、SaaSの導入も費用対効果の面で推し進めることがしづらいという課題があります。

これらの問題をまとめて解決できないまま数年過ごしてきたのですが、昨年新しいプロジェクトに入った際に思いついた方法があり、この方法を実現するための文言管理ツール hoshi を開発しています。 このツールはまだ未完成ではありますが、現在のプロジェクトで導入して一定の成果を上げつつあります。

この記事ではhoshiを作るに至った背景と、hoshi使った文言管理プロセスを紹介します。

課題とその解決策

これまで、プロジェクトに文言管理を導入した際に、以下のような課題を経験してきました。

  • 受託開発をしていた会社では、短期間で終了する複数のプロジェクトが並行して進行し、各プロジェクトで異なる管理方法が採用されていました。このため、プロジェクトごとに新しい方法を作り出したり学び直す必要があり、効率が悪い状態が続いていました。
  • 継続的に開発を行っていたアプリは多くの国で使用されており、多言語対応が求められていました。しかし、翻訳家に依頼するコストが高く、意欲的なユーザーに翻訳協力をお願いすることができないかという検討がなされました。それを実現するための適切なツールがなく頓挫してしまいました。
  • 1つのアプリに対して複数の開発プロジェクトが並行して進行している現場では。それぞれの開発がメインラインにマージされるまで、別々の文言管理が必要でした。このマージ調整には多くの工数がかかっていました。

文言管理のSaaSもありますが、機能やプロジェクト数・文言数に対して費用対効果の面で導入が難しいと考えました。

個人的な意見ですが、昨今様々なツールがSaaSモデルで作られてマネタイズしようと有料化するものが増えているものの、本当にごく基本的なことすらSaaSで有料にされてしまうのは問題ではないかと思っています。 gitとGithubのような関係で、ごく基本的なことはサーバーサイドに依存しない仕組みでできて、それをより便利にできるSaaSがあるという構造にできないかと考えています。

これらの問題を解決できないかと考えていたとき、RubyのActiveRecordのようなデータベースマイグレーション手法を文言管理に応用できるのではないかと考えました。

データベースマイグレーションでは、変更ごとにファイルを用意し、それを順番に適用することで最終的な結果を得られます。このアプローチの良い点は、変更単位でファイルをやりとりすることができ、任意のファイルで処理を停止することで、そのポイントまでの結果が得られることです。

これを実現するためのツールとして、hoshiというツールを開発しました。

hoshiの構成

hoshiは複数のYAMLファイルを含むディレクトリ構成によるファイルフォーマットと、そのファイルフォーマットを操作して変換処理をするCLIツールhoshi-cli、非エンジニア向けのフロントエンドGUIエディタhoshi Editorから構成されます。

シンプルなYAMLファイルで書かれる共通フォーマットを記述して、それをツールで変換して各プラットフォーム向けのアウトプット(例えば、iOS向けのstringsファイル、Android向けのリソースXML等)を得ます。 平易なYAMLファイルで記述されているため、gitなどのバージョン管理システムで管理したり、単純なファイルサーバーで管理することもできますし、周辺のツールを開発することも簡単にできます。

hoshiファイルフォーマット

hoshiのファイルフォーマットは、以下の構造で構成されます。

  • プロジェクト: プロジェクトは複数のパッケージを含み、グルーピングするオブジェクトです。パッケージ間で共通のデータを定義します。パッケージのディレクトリとproject.hoshiファイルで構成されるディレクトリとして保存されます。
  • パッケージ: 1つの翻訳ファイルの管理単位。出力される1つの文言データセットに対して1つ定義します。パッケージに含まれるすべてのバージョンファイルとpackage.hoshiファイルを格納したディレクトリとして保存されます。
  • バージョン: パッケージ内の変更記録の単位。ファイル名順に順番に適用された結果が出力結果となります。単純なYAMLファイルとして保存されます。 フレーズ: バージョン内に定義されている1つの文言。キーと各言語の値で構成されます。バージョンファイル内の1つのキーとして保存されます。

例えば、サーバーとアプリの文言を管理する、SomeServiceプロジェクトのデータは以下のファイル構成になります。

SomeService/
  - project.hoshi
  - app/
      - package.hoshi
      - 00000000_initial.yaml
      - 00001000_add_some_feature.yaml
  - server/
      - package.hoshi
      - 00000000_initial.yaml
      - 00001000_add_some_feature.yaml

hoshiツールセット

hoshiツールセットはTypeScriptで記述されており、CLIツールと、Electron製のGUIエディタを持ちます。 CLIツールはpkgにより、node.jsの環境がない環境でもシングルバイナリで動作するようにしています1。

hoshiの利点

hoshiを利用した文言管理プロセスには、以下のような利点があります。

  • 単一の記述で、複数のプラットフォームに対応: 1つのYAMLファイルから、iOS/Android/Windowsといった複数のプラットフォーム向けの形式に書き出すことができます。
  • 平易な管理: 複数のYAMLファイルで構成されているので、ソース管理にはgitなどの使い慣れたツールを使うことができます。
  • 平易な編集: 一般的なテキストエディタで編集が可能なだけでなく、まだ機能が十分ではないもののGUIのエディタも備えています。また、チームやプロジェクトのプロセスに沿った別ツールを作るのも簡単です。
  • オープンプロセスにも対応: ツール自体がオープンソースのため、文言管理のリポジトリを公開することで文言の管理を一般公開し、文言の修正や対応言語追加のコントリビューションを受け付けられるようにすることもできます。

僕がこれまで経験してきた課題は、hoshiを使うことで解決できそうです。

  • hoshiというツールがあることで、文言管理プロセスに一定の方向性を作り出すことができる
  • 翻訳協力を得たい場合、hoshiの文言ファイルをリポジトリに公開し、対応してもらいたい言語の変更差分を新しいバージョンファイルとしてコントリビューションしてもらうことで実現できる。
  • 複数の開発が並行する場合では、バージョンファイルの順序を調整し、特定の変更点のバージョンファイルを指定することでそれぞれの変更状態での文言を取得てソースコードに適用することができる。

hoshiの使い方

以下のGithubリポジトリで公開されています。

https://github.com/iseebi/hoshi

リリースビルドからは、CLIツールのhoshi-cliとhoshi Editorをダウンロードできます。

hoshi-cliをベースに使い方を説明します。まずプロジェクトを作成します。hoshi-cli projects createコマンドで プロジェクトが作成され、ディレクトリが作成されます。

$ hoshi-cli projects create SomeService

プロジェクトのディレクトリに入り、 hoshi-cli packages createコマンドでパッケージが作成され、ディレクトリが作成されます。このときデフォルトバージョンとして 00000000_initial.yaml も作成されています。

$ cd SomeService
$ hoshi-cli packages create app

パッケージのディレクトリに入り、hoshi-cli versions createコマンドでバージョンが作成され、YAMLファイルが作成されます。

$ cd app
$ hoshi-cli versions create 00001000_add_some_feature

YAMLファイルに決められた形式で文言を記載します。文言のテキストはJavaのString.formatの形式が記述されていることを想定して動作します。各文言ごとに $descriptionで説明を記述することもできます。

type: hoshi.version:1
phrases:
  greeting_morning:
    $description: Morning greetings.
    en: Good morning
    ja: おはようございます

最後に、hoshi publish コマンドを実行することで、hoshi形式の文言データから各プラットフォーム向けのファイルを出力できます。

$ hoshi publish

publishコマンドにバージョンを指定することで、そのバージョンまでの変更を得ることもできます。

$ hoshi publish -v 00001000_add_some_feature

その他詳しいフォーマットの機能はhoshiファイルフォーマットの仕様書をご覧ください。

今後の方向性

現在のhoshiを実際のプロジェクトに導入して使い始めています。詳細は今後紹介できればと思いますが、既にかなりの効率化ができています。

しかし、hoshiはまだまだ作り始めたばかりの未完成の状態です。 一度現状で意見をいただければありがたいと思い、記事にしてみることにしました。 コメントいただけたり、コントリビューションいただけたりするととてもうれしいです。

  1. 最初にElectronのhoshi Editorから開発を着手したため、そこにCLIを入れるという構造になってしまっていますが、node.jsバージョンがElectronに依存してしまう問題があります。pkgからSingle executable applicationsへの移行に難があるので、共通ライブラリをcliとeditorからそれぞれ参照するようにしたいという考えがあります。↩