TNT - The .NET Translation Tool

A command line tool for managing translations based on strings extracted from .NET assemblies. tnt supports translation roundtrips via Excel or XLIFF and Google machine translations.

tnt lets you mark literal strings in C# or F# source code, extracts them from the compiled IL code, and organizes the translation processes. At runtime, the NuGet [TNT.T][TNT.T] translates the marked strings.

tnt is very similar to translation solutions like gettext and was created to provide an alternative to .NET resource files.

Installation & Update

To install tnt, download the latest dotnet framework and enter:

dotnet tool install tnt-cli -g

After that, tnt can be invoked from the command line. For example, tnt version shows its current version. To update tnt enter:

dotnet tool update tnt-cli -g

Concepts & Walkthrough

Projects, Initialization, and Subdirectories

tnt works in a project's directory, preferable the directory of your application's primary project. Change into this directory an initialize it with tnt init. This creates the subdirectory .tnt/ and the file .tnt/sources.json. The .tnt/ directory contains all the important files that are managed for you: these are the list of sources and the translation files.

Note that some tnt commands act somewhat unforgiving and do not offer an undo option, therefore it's recommended to put the .tnt/ directory under revision control.

tnt init sets the source language of your project's strings to en-US by default. If your original strings are in a different language, you can change that anytime with tnt init -l [your language tag or name].

Sources

A source is something tnt retrieves original strings from. Currently, tnt supports .NET assemblies only.

All sources are listed in the .tnt/sources.json file and can be added by entering tnt add -a [relative path to the assembly] from within your project's directory. For example tnt add -a bin/Release/netcoreapp2.1/MyAwesomeApp.exe would add an assembly to the list of sources.

tnt does not read or modify any of your other project files, it accesses only the compiled assemblies.

Language & Assembly Extraction

tnt extracts marked strings from .NET assemblies. For C#, each string that needs to be translated must be marked with an extension method .t() that does two things: First, it marks the literal string that comes before it, and second, it translates the string. For example: "Hello World".t().

For more extraction options take a look at Methods of Extraction.

To use the .t() function in your projects, add the [TNT.T][TNT.T] NuGet package to your project and insert a using TNT; to the top of the source file you want to mark strings in. Lucky owners of Resharper may just type .t() after a literal string and insert using TNT; by pressing ALT+Enter.

Before extracting, you need to add at least one target language to the project. Add one, say "Spanisch" with tnt add -l Spanish.

tnt add -l and other commands accept language names or language tags. If you are not sure what languages are supported, use tnt show languages to list all .NET language tags and language names.

To be sure the sources are available, build your project and then enter tnt extract to extract the strings and to create the appropriate language files.

While tnt extracts the strings, it shows what it does and prints a status for each language file generated. After the extraction, the language files are saved to .tnt/translation-[tag].json.

The status consists of the translation's language tag, its counters, its language name, and the filename of the translation file.

Of particular interest are the counters that count the states the individual strings are in. If you extracted, say 5 strings, and haven't translated them yet, you'll see a [5n]. Later, counters for additional states will appear. If you are interested now, the section Translation States explains them all.

Translating Strings

tnt itself does not support the interactive translation of your strings, yet.

Of course, editing the translation files is possible, but there are other ways tnt can help you with:

Machine Translations

tnt supports Google machine translations, which should be a starting point for newly extracted strings. For the English to German machine translations I tried so far, the results were of good quality and Google's translation algorithm positioned .NET placeholders like {0} at the locations expected. I don't know if the resulting quality will be the same for your translations, but with tnt translate you can try your luck with the Google Cloud Translation API. For more information, skip to the section that explains tnt translate.

Excel Roundtrips

tnt export exports languages to a Excel file that can be modified by a translator and imported back with tnt import.

Although tnt tries hard to do its best, tnt import is one of the commands unexpected things may happen. So please be sure that the .tnt/ directory is under revision control.

XLIFF Roundtrips

Similar to the Excel roundtrips, tnt supports the traditional translation process that is comprised of exporting the translation files to the [XLIFF][XLIFF] format, using an XLIFF tool to edit them, and importing back the changes. With tnt export, XLIFF files are generated and sent to translators, who can then use their favorite tool (like the Multilingual App Toolkit, for example) to translate these strings and send them back to the developer. After that, tnt import is used to update the strings in the translation files.

Translation Verification

tnt supports a number of simple verification rules it applies to the translated strings. tnt verifies

• if the same .NET placeholders (for example {0}) reappear in the translated text.
• if the number of lines match.
• if the indents match.

These rules are verified with each tnt status invocation for translations that are in the needs-review state only (r for short). If one of the rules fail to verify, tnt status increases the warning counter (abbreviated with w) and tnt show warnings may be used to show the messages in detail.

Deployment & Translation Loading

tnt maintains a second directory named .tnt-content/ where it puts translation files intended to be loaded by your application via the NuGet [TNT.T][TNT.T].

These files do not need to be under revision control, because they can be regenerated with tnt sync any time. They contain distilled translations for each language optimized for your application to pick up.

The format of these files might change in the future and should not be relied on.

To make the application aware of the translation files, add them to the project and change their build action to Content.

After adding the files to the project, you can change the build action in the properties dialog of Visual Studio or by changing the XML element of the files from <Compile ... to <Content ....

Now, when you start your application with another default user interface language configured, [TNT.T][TNT.T] loads the matching translation file and translates the strings marked with .t().

Reference

Command Line, Parameters, and Examples

The tnt command line tool uses the first argument to decide what task it executes. Options are specified either with single character prefixed with - or a word prefixed with --. Some tasks take additional arguments.

For a list of available tasks use tnt help, and for options of a specific task, use tnt [task] --help. For example, tnt init --help shows what tnt init has to offer.

tnt init

Creates and initializes the .tnt/ directory. This is the first command that needs to be used to start using tnt.

• -l, --language (default en-US) Sets the source language the strings extracted are in.

  tnt init -l [language] can be used to change the source language later on.

Examples:

tnt init -l en-US initializes .tnt/ directory and sets the source language to en-US.

tnt add

Adds a new assembly to the list of sources, or a new language to the list of translations.

• -a, --assembly adds an assembly to the list of sources. The option's argument must be a relative path to the assembly.

• -l, --language adds a new translation language.

Examples:

tnt add -a bin/Release/netcoreapp2.1/MyAwesomApp.dll adds the assembly to the list of sources.

tnt add -l de adds German to the list of translation languages.

tnt remove

Removes an assembly from the list of sources.

• -a, --assembly removes an assembly from the list of sources. The option's argument may be the assembly's name or a sub-path of the assembly. As long one of the sources matches unambiguously, it's going to be removed. Use tnt status -v to list all the current sources.

Intentionally, tnt has no option for removing translation languages and expects that you delete the language file under .tnt/ manually. To update the .tnt-content/ directory, use tnt sync after that.

tnt extract

Extracts original strings from all sources and updates the translation files.

If an original string's record exists in all the translation files already, nothing changes. If it doesn't, a record is added to the translation file with its state set to new.

Records that exist in the translation files, but their original string is missing from the sources, will be set to the state unused.

If an original string reappears, for example by m