英語の情報を翻訳した際にいろいろ試した話

Last updated at 2024-03-09Posted at 2023-12-03

こんにちは。QA（Quality assurance：品質管理）チームの佐藤です。

この記事は、Supershipグループ Advent Calendar 2023の4日目の記事になります。

作業中にメモしていたことを雑多にまとめたものなので、「へーこんなことしたんだ…」的な軽い気持ちで一読していただければ幸いです。

TL;DR

Appiumの文書をローカルで翻訳
- VS CodeとDeepLを使用
成果物をWebで一時的に公開
- surge.shの利用
ネットのない環境でも閲覧できるようにPDF化
- Vivliostyleを使用

はじめに

Appiumを2.0にアップグレードする必要があり、その際、公式サイトの情報は日本語化されている部分が一部のみだったため、より詳細な部分を理解するためには、英文を読解するしかありませんでした。
はじめは、DeepLという翻訳サービスを利用して、ドキュメントをブラウザ上で読んでいたのですが、一回読んだだけではよく理解できないため、複数のページを行ったり来たりする必要があり、その都度、DeepLが翻訳するのを待つ時間（数秒ですが、操作も伴うので）が煩わしくなり、Githubの公式リポジトリからソースをクローンしてきて、自分のPC上でドキュメントを翻訳することにしました。その翻訳作業中に、いくつかの知見を得たのでその内容をまとめました。

Appiumの文書をローカルPCで日本語化

Appiumというのは、一般的には利用する機会の少ないツールなので、ご存知ない方もいるかと思います。弊社のQAチームでは、開発したSDKを実機端末上で動作確認する手作業の自動化のために利用しています。ちなみに、Appiumは、Webページの動作確認を自動化するSeleniumというツールから派生したものです。

appium　(Github)

Appiumの新バージョン（2.0）の告知があってから、長いことベータの状態で、1.0系と2.0系が併存する状態が続き、2.0をインストールする際には、明示的にコマンドでオプションを指定する必要があったのですが、本年の夏頃にアップデートした際には、明示しなくても2.0系にアップグレードされるようになっていました。
その時、ざっと調べたところでは、まだ2.0系メインで扱う記事等はほとんどありませんでした。今後は次第に置き換わっていくと思われます。しかし、そのときはとにかく情報が少ないので、使用している１.0系の環境から、2.0系の環境へと移行するための情報収集が必要です。公式のドキュメントは英語で、移行に関するページとその他の数ページのみ翻訳されている状況でした。

Appiumのドキュメント

移行手順以外にも、移行後になにか問題がありそうかどうか？みたいなものを知りたかったので、未翻訳のページをDeepLを使って翻訳しながら読みました。Google翻訳でもいいのですが、比較的自然な翻訳結果が得られるので、個人的にDeepLを課金して使っています。PDF等文書ごと翻訳できるというのもポイント高いです。

DeepL

すでに書いたように、読み解いていく過程で何度も英文からその都度翻訳したものを参照するのは効率が悪いな…ということで、翻訳結果を一旦ローカルに保存するかな？とも思ったのですが、いちいちHTMLやテキストで保存して利用するのもあまりスマートな方法とは思えないのと、原文ソースが入手できるのでは？と思い、公式リポジトリを確認してみました。

Githubからクローンしてきたリポジトリをみてみると、上層のdocフォルダは空でしたが、サイトに掲載されている原文ソースは、appium/packages/appium/docsにあるようでした。
ソースはmdファイル（markdown）なので、VS Codeで翻訳作業をしつつ、アップグレードの作業をするのにも都合がよいので助かります。

翻訳作業

ソースは、VS Codeでディレクトリを開いて、各ファイルを参照しやすいようにしておきます。
さらに、VS CodeにDeepL for Visual Studio Codeという拡張機能をインストールします。
このプラグインを使うと、VS Codeの編集画面から直接DeepLの翻訳を実行できます。
翻訳のために、enディレクトリからja ディレクトリに未翻訳のページを複製してきます。
複製してきたmdファイルをVS Codeで開き、段落ごとに選択して右クリックで翻訳をします。

私は、翻訳文章が選択箇所の下に追加されるメニューをメインに使用しました。自分の英語力に自信がなく大幅な意訳をしているため、翻訳された文章の編集が終わったら、念のため、元の英文をでコメントアウトして残してあります。

Appiumの文書の管理形態

オープンソースをはじめ、さまざなツールの国際化には、いくつかパターンがあり、他には、poファイルによるもの、翻訳サイトを利用して共同作業をしていくものなどがあります。

Appiumのサイトで公開されている文書は、リポジトリのmdファイルがMkDocsでHTMLに変換されて公開されているようです。ですので、作業の流れとしては、

mdファイルを翻訳する
MkDocsでHTMLに変換する

という感じです。自分もそのフローに従った方が、なにかと都合が良さそうです。ただ、クローンした英文を含む全文を対象に変換してしまうと、変換に時間がかかるため、時短のため、元ソースのリポジトリの構成を参考にjpフォルダ内のファイルのみ再構成するように設定ファイルを追加しました。その後、個人で確認用に利用するために、Webに一時公開したり、PDF化することもあって、最終的には別にディレクトリにデータのツリーを作成（複製？）しました。

作業のキーとなるファイル一覧：

appium/packages/appium/docs/jp/mkdocs.yaml　=> 新規作成
appium/packages/appium/docs/ja/asssets/
appium/packages/appium/docs/ja/（翻訳するmdファイル）
appium/packages/appium/docs/base-mkdocs.yml
appium/packages/appium/docs/mkdocs-ja.yml

以下、参考になりそうな部分を抜粋しておきます。
ツールの詳細などは、リポジトリと各ツール、公開されているサイトなどを参考に各自で工夫してください。

新規作成した jp/mkdocs.yaml の一部

site_name: TEST
docs_dir: ..
site_dir: ../../site

theme:
    name: material
    language: 'ja'
    palette:
      - scheme: default
        primary: deep purple
    icon:
      repo: fontawesome/brands/github
      admonition:
        note: octicons/tag-16
        abstract: octicons/checklist-16
        info: octicons/info-16
        tip: octicons/squirrel-16
        success: octicons/check-16
        question: octicons/question-16
        warning: octicons/alert-16
        failure: octicons/x-circle-16
        danger: octicons/zap-16
        bug: octicons/bug-16
        example: octicons/beaker-16
        quote: octicons/quote-16

markdown_extensions:
- footnotes
- meta
- attr_list
- admonition
- pymdownx.highlight:
    anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- pymdownx.details
- pymdownx.tabbed:
    alternate_style: true
- pymdownx.emoji:
    emoji_index: !!python/name:materialx.emoji.twemoji
    emoji_generator: !!python/name:materialx.emoji.to_svg

nav:
  - まとめ:
    - 時間がない人向けのまとめ: ja/summary.md
  - Appiumの文書:
    - はじめに: ja/index.md
  - 導入:
    - Appium入門:
      - Appiumの概要: ja/intro/index.md

    ...省略...

※ HTML生成時には、ターミナルで下記に移動します。

appium/packages/appium/docs/ja

その上で以下のコマンドを実行(Mkdocsのインストールが必要ならしておく)

mkdocs build

するとappium/packages/appium/siteにHTMLが生成されます。

appium/packages/appium/site/ja/index.html

上記をVS Codeのライブプレビューなどで確認します。

翻訳した結果を、Webで一時的に公開

手元の作業PCでは、VS Codeのライブプレビュー機能などで確認しつつ、翻訳作業を進められます。
ただ、作業の進捗確認でムフーっとするためや理解を定着させるために、外出中でも読めるように、生成されたHTMLを一時的にWeb上からも読めるようにしたいな…というように思うようになりました。

そこで、そんな目的を達成可能なサービスを探し、見つけたのが以下です。

Surge

ざっくりとした使い方は以下が参考になります。

無料で手軽！コマンド一つで静的サイトホスティングできるSurgeを試してみた。 | dotstudio

以下のコマンドでインストールし、

npm install --global surge

上記のMkDocsで生成されたsiteディレクトリ内で以下のコマンドを実行すると、生成したHTMLがアップロードされ、一時的なURLが発行されます。

surge

次回以降、発行されたサイトを更新するには、以下のフォーマットでコマンドを実行します。

surge . xxx.surge.sh

ちなみに、公開してみたのが以下です。

Appiumの文書(確認用一時公開)

注意点としては、Webアプリ的なサイトの公開やPDFなどのダウンロードサイト等には利用できないことです。文章メインのサイトの共有や、動作チェックや文章確認などには手軽でちょうどよい感じです。

翻訳した結果を、PDF化

Webに公開するだけでも問題ないのですが、ネット環境のないところで読みたい…そして、ラインを引いたりしおりを付けたりしたい…といったことはWeb上のページをブラウザで閲覧する形式では難しいです。
そこで、せっかくmdファイルもあることですし、ちょうど知人がそのようなノウハウに関する本を出版したということもあり、ちょっと興味のあったVivliostyleというツールでPDF化することにしました。

Vivliostyleというのは、md(もしくはHTML)とCSSから商業出版も可能な書籍のデータを生成できるツールです。node.jsが利用できる環境であれば、以下のコマンドで環境にインストールできます(MacOSの場合は、sudoが必要)。

npm install -g @vivliostyle/cli

PDF化に必要になるのは、以下のファイルです。

ｍｄファイル（HTMLでも可） => 原稿
cssファイル => デザイン

以下はオプションで、より品質や作業効率を向上させるために必要になります。

フォントファイル
VS Codeへプラグイン（vivliostyle-cli-helper）のインストール

上記は、単一のmdファイルをPDF化する前提の構成ですが、多数のmdファイルをマージしてPDF化する場合には、vivliostyle.conig.jsを作成した方がよいでしょう。

vivliostyle.conig.js

例（一部抜粋）

module.exports = {
  title: 'Appium ドキュメント 日本語版',
  language: 'ja',
  size: 'B5',
  theme: '@vivliostyle/theme-techbook@^1.0.0', 
  entry: [
    'text/cover.md',
    'text/index.md',
    'doc/ja/summary.md',
    'doc/ja/index.md',
    'doc/ja/intro/index.md',
    'doc/ja/readme.md',
    
    ...省略...

  ],  
  workspaceDir: '.vivliostyle', 
}

実際の作業

実際にmdファイルからPDFを作成する作業の要点をピックアップして紹介します。
詳しくは、後述の書籍をなぞりながらハンズオンするか、ネット上のチュートリアルなどを参考にしてください。

cssファイルを用意する

Webサイトの制作の時とは、@pageやbreak-before: verso;あたりがちょっと見慣れない設定かもしれません。

例（一部抜粋）

@charset "UTF-8";

* {
  box-sizing: border-box;
}

@page {
  size: 182mm 257mm;
  font-size: 10Q;
  @bottom-center {
    content: counter(page);
    block-size: 10Q;
    margin-block-start: 4mm;
  }
}

@page :left {
  margin-block: 15mm;
  margin-inline: 16mm 18.25mm;
}

@page :right {
  margin-block: 15mm;
  margin-inline: 18.25mm 16mm;
}

:root {
  font-size: 13Q;
  line-height: 24Q;
  font-family: Noto Sans JP;
  font-weight: 400;
  text-spacing: auto;
  widows: 1;
  orphans: 1;
}

p {
  font-size: 13Q;
  line-height: 24Q;
  text-align: justify;
  text-indent: 1em;
  margin-block: 0;
}

h1 {
  font-size: 36Q;
  line-height: 40Q;
  margin-block-start: 40mm;
  text-align: center;
}

h2 {
  break-before: verso;
}

mdファイルの冒頭に`YAML frontmatter`を追加する

mdファイルに下記のようなブロックを追記することで、生成されるHTMLをコントロールすることができます。
このブロックはfrontmatterと呼ばれるもので、Vivliostyleの場合は、yamlの規約に沿った値を設定することができます。

サンプル（mdファイルの冒頭を抜粋）

---
link:
  - rel: 'stylesheet'
    href: 'css/default.css'
---

## Appiumの概要
...以下省略...

mdファイルの体裁を整える

設定したルールに従い、Markdownの記述を整えます（おもにh1やｈ２など見出しの構造や、改ページの設定、複数ファイルがある場合は、目次構成など）。

mdファイルの編集画面で右クリックで変換

VS Codeの編集画面上で右クリックすると、vivliostyle-cli-helperによるメニューが表示されるので、選択します。

上記の手順でPDFを作成します。作業途中でも一息つくタイミングでビルドして、成果を確認しながら、軌道修正しながらやっていくのがいいかと思います。今回の翻訳では複数のmdファイルが存在するため、最終的に、vivliostyle.conig.jsを追加するなど、細かい調整を加え、以下のようなPDFができました。

最近では、Vivliostyleを読書のお供として活用しています。

紙の書籍の時代は、付箋をたくさん貼って参照する…みたいな感じで、重い技術系の書籍の場合、数冊購入し、家と会社においておく、電車の中で読みたい場合はカバンに入れて持ち歩くといったことをしていましたが、電子書籍をメインで読むようになった今、とてもその時代には戻れなくなってしまいました。

以前のように、付箋をたよりに、紙をペラペラめくって参照する…みたいなことはできなくなり、検索で代替していましたが、微妙に違和感というか、使いづらさみたいなものは感じていました。

理由はおそらく、今は、検索ワード自体が曖昧だったり、記憶や脳の負担になっていますが、紙の時代には、付箋の色や位置でだいたい把握していたこともあり、その辺の負担を感じなかったのだと思います。

ですので、技術書を読むときには、mdファイルにポイントをメモしながら読む…みたいなことをやり始めたのですが、mdファイルをPDF化してタブレットで見る…みたいなやり方が結構よい感じでしたので、現在はよくそうしています。
おそらく、作成したPDFが、検索ワードのインデックスみたいな感じになり、負担軽減になっているのだと思います。

より詳しくVivliostyleついて知りたくなった方は、下記を参照してください。

今後の課題

Vivliostyleは、CSSや設定ファイルを流用することで、フォーマットを揃えたコンテンツを、mdファイルから継続的に生産できます。今後は、見やすいフォーマットを研究し、パッと見で頭に内容が入ってくる配置やデザイン等でテンプレートを作成できたらなぁ…と思っています。

今回の例ではB5(182mm×257mm)を指定していますが、私が愛読している技術書はたいていが、B5変型(182mmx210mm)である場合が多いです。私は昔、書籍の編集者をしていたので、そのときに聞いたのですが、B5は紙面の広さを確保し読みやすく、内容も盛り込めます。ただ、書店の棚は、A5(148mm×210mm)がメインで設置されているので、高さをA5にして棚に収めやすいように…と意図したために、そういうサイズになっている…という話を聞きました。

個人利用目的で出版の予定もないので、わざわざ変型判を指定する必要なないな…ということで、B5にしていますが、読み慣れたサイズの方がストレスなく読める(1行の文字数や改行、改ページなど、慣れたリズムでサクサク読みたい)のかな…という気もしますので、今後は、B5変型でやっていこうかな…と思っています。

あと、Appiumの文書をせっかく翻訳したので、プルリクエストを送ってみたいけれど、あくまで自分が納得するための翻訳なので自信がなくてできない…という悩みもあります。

おわりに

最近は、VS Codeを中心？に環境が整備されてきていて、mdファイルもしくは、JSON的なファイルで記述したものをベースに、多目的に展開していくことができるようになってきているな…とひしひし感じています。

今後、どんなツールがでてくるのか…楽しみです。

最後に宣伝です。

Supershipではプロダクト開発やサービス開発に関わる人を絶賛募集しております。
ご興味がある方は以下リンクよりご確認ください。
Supership 採用サイト
是非ともよろしくお願いします。

2024.03.09追記

DeepL: Translate from ... to ... below the originalかバージョンアップで削除されました。
デフォルトだと、英文が訳文に置換されてしまい、文章の修正にすこし不便なので、元の英文を残したまま、訳文を下に挿入する形式で利用を続けたい場合は、設定で変更できます。

機能拡張の画面、歯車をクリック＞拡張機能の設定＞Deepl: Translation Mode＞InsertLineBelowを選択でそのモードになります。

Supershipグループ Advent Calendar 2023Advent Calendar 2023

Day 4

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up