コード内のコメントのローカライズ。 ヤンデックス講義

Maps APIを使用して国際市場に参入する過程で、ロシア語のコードへのコメントを停止することにしました。 同時に、サービスディレクトリはコメントに基づいて形成され、それがポータルに公開されます。ロシア語でのディレクトリのサポートを拒否したくありませんでした。 Olesya GorbachevaとMaxim Gorkunovのレポートから、YandexテクニカルライターとAPI Mapsの開発者が、コメントの言語を変更し、2つの言語でのディレクトリとサンプルの同時サポートをまとめた方法を学ぶことができます。





-私の名前はOlesyaです。MapsAPIのドキュメントを作成しています。 私は一人で話すのではなく、同僚のマキシムが私と一緒にいます-Yandexのローカリゼーションツールを担当しています。



今日は、JS Maps APIコードのコメントで言語の変更方法について説明します。 私たちは何をしましたか？ コード内のロシア語のコメントはすべて英語のコメントに変更されました。 レポートの過程で、コード内のコメントを翻訳する必要があった理由、このタスクの複雑さ、およびコードからのドキュメント自動生成システムにどのように影響したかを説明します。 コード内のコメントだけでなく、ドキュメントを翻訳し、それに基づいてYandexでAPIディレクトリをコンパイルおよび公開する必要がありました。 ドキュメントとローカリゼーションサービスだけでなく、API Mapsチームもこのタスクに取り組みました。これらの面白い人はタスクの顧客であり、機会のヒーローです。



コメントを翻訳するタスクはどのようにコードに表示されましたか？ コードがまだロシア語で文書化されていた時代に戻りましょう。 昨年のHyperbatonで、JSDocツールを使用してコードを文書化することを既に述べました。





開発者は、JSDocの要件に従ってコードをロシア語でマークアップしました。 必要に応じて、これらの要件を読み、コードに変更を加えてコミットします。



どの参考書をサポートしましたか？ まず、コードはロシア語です。 DITA XMLはドキュメントを表示するための形式であり、Lesha Mironovのレポートに詳細が記載されています。 ここにコンパイルされたガイドの例を示します 。



ロシア語のディレクトリだけでなく、英語もサポートしました。 収集したロシア語のハンドブックを翻訳用に渡し、ハンドブックを英語で受け取りました。 これも公開されましたが、すでにcomドメインにあります 。



英語のディレクトリに問題がありました。 コメントの編集は非常に頻繁に行われます。 APIのリリースサイクルはかなり短くなっています。 少なくとも毎日、ロシア語のディレクトリを迅速に公開できれば、翻訳のために毎日それを提供する余裕はありません。



そのため、数か月に一度、多数の変更を蓄積し、翻訳用のハンドブックを配布しました。 そして、英語のディレクトリはロシアに遅れをとっていました。 当時、ロシアの文書がより優先され、私たちにとっては受け入れられました。



時間が経つにつれて、Maps APIが開発され、世界中の視聴者の増加が顕著になりました。







世界のさまざまな地域の人々が、Maps APIの使用に関する質問とドキュメントへの質問で頻繁に私たちに手紙を書き始めました。なぜそこに古いバージョンがあるのですか。 その瞬間、私たちは半年前に、まずYandexは国際企業であり、map APIは大規模なプロジェクトであると考え始めました。 そして、世界中のユーザーがコードを開いてロシア語のコメントを見ることができます。 これは間違っています。



さらに、その時点で、開発者はGitHubにあるAPIを操作するための外部モジュールをリリースし始め、それらのドキュメントはすぐに英語で書かれています。 また、英語のディレクトリのバックログも忘れないでください。 これをすべて検討した後、すべてのコメントを英語に翻訳し、すぐに英語で書くべきだと考えました。



タスクの難しさは何ですか？ そのとき、map APIコードには正確に4,703個のコメントがあると計算しました。 それらのいくつかは十分に大きいです。 これは1つのフラグメント、1つのコメントです。 それらはすべてそれほど長くはありませんが、それでもなお。







このすべてを翻訳する必要がありました。 そして、ゼロから翻訳しません。 ディレクトリの長年にわたる翻訳の間に、膨大な翻訳メモリを蓄積してきました。これは通常のXMLドキュメントを翻訳する場合にのみ使用できます。 このメモリを使用してコード内のコメントを翻訳する方法を学びたかったのです。



手動で翻訳したくありませんでした。 手作業でコード4700のコメントにコピー、翻訳、コピーして戻したくありませんでした。 コメントを自動的に抽出し、その場所に翻訳を挿入し、コード自体を壊すことなく、JSドキュメントのスケルトン、すべてのJSDocタグ、それらの有効性を維持したかったのです。 マキシムはこれをどのように行ったかについて語ります。



-こんにちは。 技術的な詳細を追加し、このタスクがローカライズエンジニアの観点からどのように見えるかを説明します。



クラス、オブジェクト、メソッドのすべての記述をJSコードで見つけ、すべてのパラメーターのテキスト記述を見つけて、このすべてのテキストをXLIFFファイルの形式で提示する必要がありました。 Yandexでは、全員がXLIFFを使用した翻訳に努めており、そのためのプロセスをデバッグしています。翻訳ファーム、翻訳メモリを保存するサーバーTMがあります。 実際、すべてのJSスクリプトからXLIFFを作成し、それをCatツールに変換する必要がありました。 このタスクでは、ローカリゼーションタスクを自動化するために使用する強力なオープンソースツールであるOkapiフレームワークを使用しました。



ソースJSファイルをリポジトリから取得し、要件、UTF-8エンコーディング、同じ行末を満たしていることを確認しました-これはCatツールが機能するために重要です。



次に、Okapiフィルターの1つを適用するために、それらを準備する必要がありました。 JSDocはJSファイルを文書化するための最も強力なツールですが、フィルターはありません。 なんとか出なければなりませんでした。 Dapigenコメントを抽出するOkapi Frameworkの最も近いフィルターを使用しました。 これは、C ++、Java、および場合によってはPythonでのコメントに主に使用される別のコードドキュメントシステムです。



これらのコメントの形式は非常に似ています。 実際、これらのJSファイルを偽造し、Doxygenフィルターが期待する外観にする必要がありました。 違いは主にアスタリスク、スラッシュにありました。 コメントを打つために2つではなく3つのスラッシュが必要だとします。1つではなく2つの星も必要です。 このコードを少し変更しました。 プログラマーの観点からは無効になりましたが、これらのフィルターは解析しないため、テキストファイルのようなものであり、私たちにとっては問題ではありませんでした。



構成をセットアップし、すべてのJSDocパラメーターを指定して、それらからテキストのみを取り出すようにしました。 公式のプログラミングには興味がなく、ロシア語のテキストにのみ興味がありました。



次に、パイプラインを作成しました。 Okapiフレームワークの用語では、これはXLIFFの作成につながる一連の手順です。 次はセグメンテーションのステップでした。 ロシア語用のSRXファイル形式のルールがあります。これにより、テキストの大きなブロックを個別の文に分割できます。 これにより、メモリの断片が小さくなるにつれて、TMからの一致の割合が増加します。



次に、ディレクトリから残した既存のTMを適用し、あいまいで明確な一致を取得し、結果の巨大なXLIFFファイルをCatツールに転送しました。



ここでXLIFFファイルを使用したのは、Okapiとの親友であり、これらのXLIFFはオンラインツールで翻訳できるためです。



次に、受け取った翻訳を編集し、すべてがその場でうまくいったかどうかを確認する必要がありました。 コメントとアスタリスクの詳細のため、かなり難しいタスクがありました。 私たちのバージョンに5行ある場合、翻訳も同じ5行にする必要があります。そうしないと、巨大なシートが腐食し、フォーマットが壊れます。 これを行うために、欠落しているスペース、改行の特別な修正を作成し、インラインタグを賢くチェックしました。 何かがスキップされた場合、ソースから置き換えられました。



次に、取得したTMをさらに使用するために抽出しました。



後処理、完全にミラーベースの前処理を行う必要がありました。 有効なJSファイルを返して、Doxygenフィルターが機能するために必要なすべてのものを削除する必要がありました。



その結果、同じJSファイルのセットを取得しましたが、すべてのコメントはすでに英語になっています。 マップチームの開発者はテストを作成し、すべての変更がコメントが配置されている領域でのみ発生すること、つまりコードを損なわないことを確認しました。 それはそのような冒険でした。





-デモとして、現在のソースコードからのフラグメント。 しかし、これでは、タスクはまだ最後まで解決されていません。 コード内の英語のコメントを誰が編集するのか、そして最も重要なこととして、どのように編集するのかを考える必要がありました。



また、コメントの言語が変更されたため、自動生成システムを適合させる必要がありました。 これをどのように解決しましたか？ 翻訳エディターとして翻訳者のAmyを選びました。 AmyはYandexのほぼすべての技術文書、特にMaps APIを翻訳しています。 カードの開発者は、エイミーの人生を最大限に簡素化することを望んでいました。 彼らは、Amyがコード内、コメント内のすべての変更を手動で追跡することを望んでおらず、Gitコマンドを使用してコンソールで作業する必要がないことを望んでいました。



したがって、AmyはNode.jsで簡単なスクリプトを作成しました。Amyは日付を操作し、この間にコードに含まれるすべてのコミットのリストを取得します。



たとえば、Amyはそのうちの1つを通過し、内部のGitHubのインターフェースに入り、そこで緑色のライトでコメントに加えられた変更を確認します。 Amyは、ボタンを使用してコードを読み取り、必要に応じて修正し、コミットします。 すべてがシンプルです。 もちろん、ここでは余分なものをコミットしないように注意する必要があります。 また、エイミーは、コードを読むことによって私たちが犯す典型的な間違いをすべて修正します。 技術的な英語でテキストを書くときに私たちが犯す間違いについてです。 以下に記事にエラーがある例を示しますが、このようなラベルはもっとたくさんあります。 将来このような間違いを避けることをお勧めします。



自動生成システムをどのようにセットアップして適合させたか。 過去に戻って、ロシア語のコードにコメントがあることを想像してみましょう。 APIは以前どのように形成されましたか？



ロシア語のディレクトリを作成するために、JSDocを介してロシア語のコメントを含むAPIのソースコードを実行しました。 しばらく時間がかかり、JSDocは必要なDITA XMLを返しました。これは、ドメインruで公開した既製の参照です。 ここでは簡単です。



ロシア語のコメントから英語のディレクトリを取得する方法は？



私たちはロシアのコードを取得し、別のイテレーションで再度JSDocを実行しましたが、英語用にローカライズされた特別なテンプレートをセットアップしました。 たとえば、テーブルの名前はすぐに英語でした。 このようなテンプレートの存在を英語のヘルメットでマークします。 英語のJSDocはDITA XMLを提供しましたが、それでも翻訳のために提供したロシア語の説明がありました。 Amyが翻訳して、英語でDITA XMLを返しました。これは、comドメインで公開できる既製のリファレンスです。



良いですが、それは以前でした。 現在、すべてが変更されています。コメントは英語です。 英語のディレクトリをどのように収集しますか？ 前と同じように、彼らはロシア語を集めました。 ソースコードを取得し、英語のプログラマーJSDocで実行し、英語のソースを取得し、comドメインで公開します。 ロシアのディレクトリはどうですか？ コードには英語のコメントが含まれており、長年にわたって蓄積してきた翻訳メモリであるTMがあります。



ロシア語から英語に翻訳するときにTMを使用しました。 そして、英語からロシア語に翻訳するときに、逆方向に機能する場合はどうなると思いましたか？ エイミーとマックスは一連の実験を実施しましたが、実際にはそうでした。 長年にわたって蓄積されたTMを逆方向に適用できます。



これは、英語を収集するために使用したのと同じスキームに従って、現在ロシアディレクトリを実行していることを意味します。 ここでの主なことは混乱しないことです。ソースコードを英語のコメントで取得し、JSDocで実行しますが、ロシア語にローカライズされたテンプレートを使用し、テーブル名をロシア語にします。 翻訳用の参考図書を提供し、ロシア語に翻訳して公開します。



翻訳者として、私はすでにここで話しています。 ロシア語のガイドを発行する必要があるたびに、最初に英語を収集し、Swordfishツールで、これまで翻訳されていないテキストの欠落部分を翻訳してから、発行します。 最初に翻訳したディレクトリが常に遅れていることを示すカタツムリを覚えていますか？ 今、主なことは、ロシアのディレクトリが遅れていないことでした。 まず第一に、私は翻訳に携わっているという事実のために時間が短縮されました。 翻訳のために並んでいる必要はありません：開いて、数行を翻訳し、自分ですべてを集めました。



TeamCityは、ディレクトリの同期を支援しました。 これは、プロジェクトの多くのプロセスを自動化できるJetBrainsのツールです。 強力なもの。







これは、カスタマイズされた内部TeamCityインターフェースの例です。 これは、ディレクトリを構築するための設定例です。 必要なパラメータがそこに設定され、ディレクトリの言語、バージョン番号など、ボタンが起動し、必要なソースが準備されます。 最後に、英語版のPDFも生成します。 以前はこれをしませんでした。



コード内でコメントをローカライズする利点は何ですか？ まず、Maps APIには英語のコメントが含まれるようになったため、世界中の開発者が英語を見ることができます。 次に、最後に、英語のドキュメントの運用レイアウトを設定しました。 第三に、翻訳者から負荷を取り除きました-現在、エイミーはこれらのディレクトリを毎回翻訳する必要がありません。 そして最後に、いつかディレクトリを他の言語に翻訳する必要がある場合、英語からの翻訳はロシア語からの翻訳よりもはるかに簡単です。



これらは、プロジェクトで使用するツールのリストです。 よろしくお願いします！