ベースファイルの検証

English | Français | 한국어 | 日本語

何を検証しますか？

MMG は主に以下の内容を検証します。

• 使用者が使用した各タグの数が同じかどうか
• すべてのタグが一度ずつ現れる前に、重複したタグが再び現れるかどうか
• 事前に指定されたタグ以外のタグがあるかどうか
• no-suffix オプションが正しく設定されているかどうか

検証に合格しない場合は、このページで説明する Verbosity 設定を通じて、使用者に検証に合格しない理由を知らせることができます。 検証に合格しなくても強制的に変換することができます。

使用されたタグの数が同じかどうか

使用者が抜けているタグがあるかどうかを確認するために、MMG は使用者が使用した各タグの数を数えて比較します。

Validation 失敗Validation 通過

B を抜けたため、検証に合格しません。

<!-- multilingual suffix: A, B, C -->

<!-- [A] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [C] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

<!-- multilingual suffix: A, B, C -->

<!-- [A] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [B] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [C] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

すべてのタグが一度ずつ現れる前に、重複したタグが再び現れるかどうか

ドキュメント全体を見ると、すべてのタグが同じ回数使われていたとしても、すべてのタグがセットでまとめて現れない場合は、検証に合格しません。

このように検証する理由は、すべてのタグが均一に現れない場合、使用者がどのタグを抜けたかを知るのが難しいためです。 しかも使用されたタグの数が同じであるため、ドキュメントが長くなるとなおさら知るのが難しいです。 この検証を通じて、潜在的に発生する可能性のある問題を事前に防ぐことができます。

Validation 失敗Validation 通過

A, B, C に抜けた内容がないため、MMG が生成する内容には問題がありません。 しかし、A と B が現れた後、A が再び現れたため、検証に合格しません。

<!-- multilingual suffix: A, B, C -->

<!-- [A] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [B] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

<!-- [A] -->
Aenean in ultrices metus, in semper mi.
<!-- [B] -->
Aenean in ultrices metus, in semper mi.

<!-- [C] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [C] -->
Aenean in ultrices metus, in semper mi.

A, B, C が必ずしも順番に現れる必要はありません。

<!-- multilingual suffix: A, B, C -->

<!-- [C] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [A] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [B] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

<!-- [A] -->
Aenean in ultrices metus, in semper mi.
<!-- [B] -->
Aenean in ultrices metus, in semper mi.
<!-- [C] -->
Aenean in ultrices metus, in semper mi.

事前に指定されたタグ以外のタグがあるかどうか

使用者はいつでもタイプミスをする可能性があるため、MMG が使用者定義タグを読むとき、ヘッダーに宣言されたタグかどうかを確認します。

Validation 失敗Validation 通過

ko を kr と間違って入力し、ja も jp と間違って入力したため、検証に合格しません。

<!-- multilingual suffix: ko, ja -->

<!-- [kr] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [jp] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

<!-- multilingual suffix: ko, ja -->

<!-- [ko] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [ja] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

no-suffix オプションが正しく設定されているかどうか

Validation 失敗Validation 通過

en-US は使用者定義タグではないため、検証に合格しません。

<!-- multilingual suffix: ko, ja -->
<!-- no suffix: en-US -->

<!-- [kr] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [jp] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

<!-- multilingual suffix: ko, ja -->
<!-- no suffix: ko -->

<!-- [ko] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<!-- [ja] -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Verbosity 設定

Note

GitHub リポジトリに Verbosity 設定を試験できる例題ファイルがあるので、使ってみてください。 (例題ファイルの位置: ./examples/validation-examples)

Verbosity は 0 がデフォルト値なので、普段の MMG は検証結果だけを出力します。

$ mmg -r
----------------------
 ❌ bad_md.base.md
 ✅ good_md.base.md
 ❌ bad_jupyter.base.ipynb
----------------------
 => 3 base files were found.
    Do you want to convert these files? [y/N]

しかし Verbosity 設定をすると、検証に合格しない理由を知ることができます。

Verbosity 1 (--verbose または -v)

Verbosity が 1 なら、タグの数が追加で出力されます。これによって、抜けたタグやタイプミスの有無を素早く確認することができます。

$ mmg -r -v
----------------------
 ❌ bad_md.base.md
    3 language(s) not translated.
    Tag count: {'A': 4, 'B': 2, 'C': 2, '<Unknown>': 1}
 ✅ good_md.base.md
    Tag count: {'A': 3, 'B': 3, 'C': 3}
 ❌ bad_jupyter.base.ipynb
    1 language(s) not translated.
    Tag count: {'en-US': 2, 'fr-FR': 2, 'ko-KR': 2, 'ja-JP': 2, '<Unknown>': 1}
----------------------
 => 3 base files were found.
    Do you want to convert these files? [y/N]

Verbosity 2 (--verbose --verbose または -vv)

Verbosity を 2 に設定すると、具体的に何行目がどの理由で検証に合格しなかったかを知ることができます。 特に、jupyter notebook の場合、どのセルのどの行が検証に合格しなかったかを知ることができるため、レンダリングされたセルを一つ一つ確認する必要がありません。

$ mmg -r -vv
----------------------
 ❌ bad_md.base.md
    3 language(s) not translated.
    Tag count: {'A': 4, 'B': 2, 'C': 2, '<Unknown>': 1}
        Config: no_suffix 'en-US' is not in lang_tags.
        Line 10: Unknown tag 'D' detected.
        Line 12: 'common' appeared before all tags appeared once.
        Line 18: 'A' appeared again before all tags appeared once.
        Line 22: 'common' appeared before all tags appeared once.
        Line 28: 'common' appeared before all tags appeared once.
        Line 34: 'common' appeared before all tags appeared once.
 ✅ good_md.base.md
    Tag count: {'A': 3, 'B': 3, 'C': 3}
 ❌ bad_jupyter.base.ipynb
    1 language(s) not translated.
    Tag count: {'en-US': 2, 'fr-FR': 2, 'ko-KR': 2, 'ja-JP': 2, '<Unknown>': 1}
        Cell 4, Line 3: Unknown tag 'English' detected.
----------------------
 => 3 base files were found.
    Do you want to convert these files? [y/N]

検証をスキップする

-s または --skip-validation オプションを使うと、検証をスキップすることができます。 このとき、markdown ファイルは 📄 で表示され、jupyter notebook ファイルは 📒 で表示されます。

$ mmg -r -s
----------------------
 📄 bad.base.md
 📄 good.base.md
 📒 sample_jupyter.base.ipynb
----------------------
 => 3 base files were found.
    Do you want to convert these files? [y/N]

CI/CD のための検証 only モード (ファイル生成無効化)

v2.0.0 から使える機能です。

このモードは検証のみを行い、変換されたファイルを生成しません。 このモードは CI/CD のために作られたため、検証に合格しない場合は sys.exit(1) を呼び出します。 検証に合格すると sys.exit(0) を呼び出します。 これを利用して、検証の結果によって CI/CD パイプラインの分岐を分けることができます。

mmg -r --validation-only
----------------------
 ❌ bad_md.base.md
 ✅ good_md.base.md
 ❌ bad_jupyter.base.ipynb
----------------------
 => 3 base files were found.
 => Some files are unhealthy.

Verbosity 設定を通じて、検証に合格しない理由も CI/CD ログに残すことができます。

$ mmg -r --validation-only -vv
----------------------
 ❌ bad_md.base.md
    3 language(s) not translated.
    Tag count: {'A': 4, 'B': 2, 'C': 2, '<Unknown>': 1}
        Config: no_suffix 'en-US' is not in lang_tags.
        Line 10: Unknown tag 'D' detected.
        Line 12: 'common' appeared before all tags appeared once.
        Line 18: 'A' appeared again before all tags appeared once.
        Line 22: 'common' appeared before all tags appeared once.
        Line 28: 'common' appeared before all tags appeared once.
        Line 34: 'common' appeared before all tags appeared once.
 ✅ good_md.base.md
    Tag count: {'A': 3, 'B': 3, 'C': 3}
 ❌ bad_jupyter.base.ipynb
    1 language(s) not translated.
    Tag count: {'en-US': 2, 'fr-FR': 2, 'ko-KR': 2, 'ja-JP': 2, '<Unknown>': 1}
        Cell 4, Line 3: Unknown tag 'English' detected.
----------------------
 => 3 base files were found.
 => Some files are unhealthy.