콘텐츠로 이동

Base 파일 유효성 검사

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

어떤 것을 검사합니까?

MMG는 주로 다음의 내용을 검사합니다.

  • 사용자가 사용한 각 태그의 개수가 동일한지 여부
  • 모든 태그가 한 번씩 나타나기 전에, 중복된 태그가 다시 나타나는지 여부
  • 미리 지정된 태그가 아닌 태그가 있는지 여부
  • no-suffix 옵션이 제대로 설정되었는지 여부

검사를 통과하지 못하면, 이 페이지에서 설명할 Verbosity 설정을 통해 사용자에게 검사를 통과하지 못한 이유를 알려줄 수 있습니다. 검사를 통과하지 못했더라도 강제로 변환할 수 있습니다.

사용된 태그의 개수가 동일한지 여부

사용자가 빠트린 태그가 있는지 확인하기 위해, MMG는 사용자가 사용한 각 태그의 개수를 세어서 비교합니다.

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.

모든 태그가 한 번씩 나타나기 전에, 중복된 태그가 다시 나타나는지 여부

문서 전체를 볼 때, 모든 태그들이 동일한 횟수로 사용되었더라도, 모든 태그들이 세트로 묶여서 나타나지 않으면 검사를 통과하지 못합니다.

이렇게 검사하는 이유는 모든 태그들이 균일하게 등장하지 않으면, 사용자가 어떤 태그를 빠트렸는지 알기 어렵기 때문입니다. 심지어 사용된 태그의 개수가 동일하기 때문에, 문서가 길어진다면 더더욱 알기 어렵습니다. 이 검사를 통해, 잠재적으로 발생할 수 있는 문제를 미리 방지할 수 있습니다.

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가 사용자 정의 태그를 읽을 때, 헤더에 선언된 태그인지 확인합니다.

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 옵션이 제대로 설정되었는지 여부

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 설정

안내

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.