Skip to content

Latest commit

 

History

History
227 lines (149 loc) · 9.94 KB

README.ja_JP.md

File metadata and controls

227 lines (149 loc) · 9.94 KB

PourOver

PourOverはコマンドラインツールで、CSVファイルに格納された複数の言語で表現された文字列リソースに対して、各文字列に組み込まれたトークンが適切かどうかを言語間で比較して診断します。

CSVファイルの構造

CSVファイルはUTF-8でエンコードされ、1行目はヘッダーになります。ヘッダーの一番左のフィールドは使用されません。それ以外のフィールドは、各列の言語名を記載します。ヘッダーは診断の対象ではありませんが、一番左のフィールドを除き、フィールドの内容を診断メッセージで使用します。

ヘッダーに続く、二行目以降の行は、メッセージのIDと、各言語毎の文字列になります。次のような内容の文字列リソースを例とします:

ID English Japanese
HELLO Hello こんにちは
BYE Bye さようなら

CSVファイルは以下のようになります:

ID,English,Japanese
HELLO,Hello,こんにちは
BYE,Bye,さようなら

トークン

トークンは文字列リソースに組み込まれたプレイスホルダーで、ブレース（{と}）で囲まれた文字列です。例えば、次のような内容の文字列リソースがあるとします:

ID English Japanese
TIME It's {hour} o'clock. {hour}時です。
DEAR Dear {name}, 拝啓 {name} さん、 　

TIMEの文字列リソースでは、どの言語においてもトークン{hour}が組み込まれ、表示する際に{hour}は現在の時刻の（時分秒の）時に置き換えられます。また、DEARでは、同様に{name}が組み込まれ、表示する際に{name}は人名に置き換えられます。

文字列リソースはトークンを複数含むことができます。

診断メッセージ

診断メッセージは次のような形式になります:

ファイル名 : 行番号 : ID : メッセージ

--verboseを指定すると次のような形式になります:

ファイル名 : 行番号 : ID : （ 診断ID ) メッセージ

トークンの診断

多くの場合、トークンは言語が変わっても、出現する個数は変わりません（出現順序が異なることはあります）。例えば、ある文字列リソースで、言語 A がトークン{foo}と{bar}を含み、言語 B がトークン{foo}と{baz}を含むなら、何か間違っている可能性があります（もちろん、例外的に間違っていない場合もあります）。このように、簡単なヒューリスティックスを使って、トークンを診断することが可能です。

次のト－クンの診断があります:

  • TypeNumberMismatch
  • StrayToken
  • FrequencyMismatch

TypeNumberMismatch

ある文字列リソースで、トークンの種類の数が言語によって異なる場合に報告します。例えば、言語 A は{foo}、{bar}、{baz}の三種類のトークンを含み、言語 B は{foo}、{bar}の二種類のトークンしか含まない場合が該当します。同じトークンが複数回出現しても、種類としては1つとして数えます。

例えば、次のような文字列リソースを考えます:

ID English Japanese
EXAMPLE1 Hello {foo} {bar} こんにちは {foo}
EXAMPLE2 Bye {foo} {bar} さようなら {foo} {foo}

このとき、次のような診断を出力します（ロケールが英語の場合）:

file.csv:2: EXAMPLE1: The number of unique tokens is different: 'English' has 2 token(s) but 'Japanese' has 1 token(s).
file.csv:3: EXAMPLE2: The number of unique tokens is different: 'English' has 2 token(s) but 'Japanese' has 1 token(s).

なお、このTypeNumberMismatchが診断された場合、そのフィールドに対しては以降の診断を実施しません。

StrayToken

ある文字列リソースで、トークンの種類が言語によって異なる場合に報告します。例えば、言語 A は{foo}、{bar}のトークンを含み、言語 B は{foo}、{baz}のトークンを含む場合が該当します。

例えば、次のような文字列リソースを考えます:

ID English Japanese
EXAMPLE1 Hello {foo} {bar} こんにちは {foo} {baz}

このとき、次のような報告を出力します（ロケールが英語の場合）:

file.csv:2: EXAMPLE1: Token {bar} appears only in 'English'.
file.csv:2: EXAMPLE1: Token {baz} appears only in 'Japanese'.

なお、このStrayTokenの診断を報告した場合は、以降の診断を実施しません。

FrequencyMismatch

ある文字列リソースで、特定のトークンの出現回数が言語によって異なる場合に報告します。例えば、言語 A はトークン{foo}を一つだけ含み、言語 B はトークン{foo}を二つ含む場合が該当します。

例えば、次のような文字列リソースを考えます:

ID English Japanese
EXAMPLE1 Hello {foo} {foo} こんにちは {foo}

このとき、次のような報告を出力します（ロケールが英語の場合）:

file.csv:2: EXAMPLE1: Token {foo} appears 2 time(s) in 'English' but appears 1 time(s) in 'Japanese'.

そのほかの診断

そのほか次の診断があります:

  • InvalidToken
  • DuplicateID

InvalidToken

フィールド中のブレース（{と}）の対応が間違っていて、トークンをパースできないときに報告します。例えば、次のような文字列リソースを考えます:

ID English Japanese
EXAMPLE1 Good morning {foo} おはようございます {foo
EXAMPLE2 Good afternoon {foo} こんにちは foo}
EXAMPLE3 Good evening {f{oo} こんばんは {foo}

このとき、次のような報告を出力します（ロケールが英語の場合）:

file.csv:2: EXAMPLE1: ’Japanese’ has an invalid token: Missing a closing brace ('}')
file.csv:3: EXAMPLE2: ’Japanese’ has an invalid token: Missing an opening brace ('{')
file.csv:4: EXAMPLE3: ’English’ has an invalid token: Token containing an opening brace ('{')

なお、このInvalidTokenの診断を報告した場合は、そのフィールドはトークンが含まれないものとみなして以降の診断を続行します。

DuplicateID

CSVファイルでIDの重複があると報告します。例えば、次のような文字列リソースを考えます:

ID English Japanese
EXAMPLE1 Hello {foo} こんにちは {foo}
EXAMPLE1 Bye {foo} さようなら {foo}

このとき、次のような報告を出力します（ロケールが英語の場合）:

file.csv:3: EXAMPLE1: This ID already appeared at line 2.

Requirements

Get started

PourOverはNuGetパッケージで利用可能です。次のようにインストールできます:

dotnet tool install -g PourOver.GlobalTool

Synopsis

PourOver [-L CULTURE] [-hbvV] [--] FILE.csv

Description

FILE.csvは前述した構造のCSVファイルです。

オプションは次のようになります:

Option Description
-L, --culture CULTURE カルチャーを指定します（例: en-US）
-h, --help ヘルプメッセージを表示して終了します
-b, --ignore-blank 空欄のフィールドを無視します
-v, --verbose 出力が冗舌になります
-V, --version バージョンを出力して終了します

Exit status

PourOverは正常に終了した場合、終了ステータス0で終了します（診断の有無とは無関係です）。CSVファイルのフォーマットが壊れているなどのエラーが検出された場合は、正の整数で終了します。

How to build

Requirements to build

Build with .NET Core SDK

git clone URL
cd PourOver
dotnet restore
dotnet build

Get test coverage report with Coverlet

dotnet test -p:CollectCoverage=true -p:CoverletOutputFormat=opencover \
        --no-build PourOver.Test
dotnet ANYWHERE/reportgenerator.dll \
        --reports:PourOver.Test/coverage.opencover.xml \
        --targetdir:Coverlet-html

Install PourOver as a Global Tool

cd PourOver.GlobalTool
dotnet pack
dotnet tool install --global --add-source bin/Debug PourOver.GlobalTool