@hejdoktor/resx-compiler

resx-compiler

Compiles a resx file into typescript.

The compiled file will expose the available translations, so that the typescript compiler can help enforce valid usage.

Usage

Note that for server-side this should be added as a regular dependency, since it exposes a format function that the compiled translation files will import. For a client-side bundle, it does not matter, as long as the dependency is available at build-time.

Files can be generated using npx resx-compiler <source folder>. The code will detect all .resx files and generate a sibling .resx.ts file with the content.

This content can then be accessed via import { R } from "foo.resx". The R object have all the translations on it, via R.someTranslation.

Multiple languages

If there are multiple locales for the .resx files (eg. foo.resx and foo.en.resx or bar.da.resx and bar.en.resx), the system requires a default locale to be set. This is done by adding the --default-locale <locale> option:

npx resx-compiler --default-locale en <source folder>

This will result in multiple files being created for each resource, so if da and en are the available locales, three files will be created:

• foo.resx.ts
• foo.da.resx.ts
• foo.en.resx.ts

All can be imported, but only the base file is recommended. It loads the correct resources from the current locale, which can be set by importing setLocale and then calling it with the correct locale:

import { setLocale } from "@hejdoktor/resx-compiler"

setLocale("da")

It defaults to the --default-locale option until it is called the first time.

The supported set of translations are defined by the default locale, and any missing keys in other locales will automatically get the value from the default translation.

Optimizing builds

Translations can take up a lot of space, and users typically only need one language at a time. The resulting file can be optimized by running the bundler with the enforcedLocale environment variable set to the appropriate locale. This will ensure that the other languages cannot be chosen, and tree shaking from the optimizer will remove non-matching translations.

This should be used to produce one bundle per locale, which the server can then load directly to serve as little code as possible to a client.

Unusual translation names

If a translation name contains . or -, the translation will be added with the original name, but it will also follow the convention of the C# resx compiler and replace the character with _. This means that foo.bar-baz can be accessed both as R["foo.bar-baz"] and R.foo_bar_baz

Replacement strings

If the translation contains replacement points, a format-function that follows the same rules as C#'s string.Format() is exposed along with the resources: import { R, format } from "foo.resx". It can also be fetched from the library directly: import { format } from "@hejdoktor/resx-compiler".

For a translation <data name="foo"><value>Some {0} value {1}</value></data>, it can be used like so: format(R.foo, "bar", "baz").