Optionally show source context next to reference paths & line numbers

Added optional support for showing the source code context next to the source file path and line number. This helps provide a bit more context for translators who don't have access to the source code.

To enable the feature, add the /source or -source option to i18n.PostBuild.exe command line.

We have private git repos which we do not share with our translators, but often some terse extracted nuggets can be clarified simply by looking at the original source line. So I added an option that includes the actual source after the source filename & line number.

When the option is enabled, it would turn an ambiguous message definition of %0 Parameter like this:

#: Views\StatisticDefinition\Form.cshtml:118
msgid "%0 Parameter"
msgstr ""

into something a bit more clear like this:

#: Views\StatisticDefinition\Form.cshtml:118 [[[Licence Details]]]: @ViewBag.PoolSize - [[[Active]]] - @Model.Type - [[[%0 Parameter|||@Model.ParameterName]]] - [[[Statistic Definitions]]]
msgid "%0 Parameter"
msgstr ""

Context like the above is often enough for a tech-savvy translator, (who knows our product domain and knows our software has a view which shows the parameter name of various statistics) to recognize the English text in context, and reason on their own that %0 Parameter is a substitution expression for various environmental monitoring parameters like "Accumulated Rain Fall Parameter", and a 'parameter' in the general computer-science context.

It probably isn't safe to always the source context after the reference path and line number. There are plenty of "PO editor" implementations out there, and they might not expect it. It certainly works for the two I've tried (Poedit and Sisulizer), but who knows what else might fall over.

Changes:

1) Added a PathNormalizer class to eliminate hard-coded paths showing up in the generated messages.po files

Consider this project folder structure:

src\
  ProjectA\
    Foo.cs:     return "[[[Foo]]]";
  ProjectB\
    Bar.cs:     return "[[[Bar]]]";
    web.config: <add key="i18n.DirectoriesToScan" value=".;..\ProjectA" />

Without path normalization, the following file would be generated:

# Bar.cs:88
msgid "Bar"
msgstr ""

# C:\Users\Fred.Derf\Documents\MyLittlePonyFanFiction\git\SuperSecretRepoName\ProjectA\Foo.cs:55
msgid "Foo"
msgstr ""

That full path is not really needed, and just adds to the noise in the generated file.

With path normalization, the generated file contains relative path references to ProjectA:

# Bar.cs:88
msgid "Bar"
msgstr ""

# ..\ProjectA\Foo.cs:55
msgid "Foo"
msgstr ""

The anchor path for normalization is the config file (web.config in this example).

If the path being normalized shares any common root with the anchor path (ie. they exist on the same drive), then a relative path will result. If the path has nothing in common with the anchor path, then the full absolute path is returned. There's nothing to normalize in that case.

2) Added a ReferenceContext class to replace the separate referencePath string and lineNumber integer in the nugget extractor code.

The ReferenceContext class also contains a Context property from where the nugget was extracted. If the global ShowSourceContext flag is true, then this context will be added to the comment line in the generated file.

3) Cleaned up the outer console program logic

The i18n.PostBuild.exe tool will now exit with a zero exit code if successful. If anything goes wrong, it exits with a positive exit code. This helps build scripts detect failures when things go sideways.

turquoiseowl / i18n

Optionally show source context next to reference paths & line numbers #268