H073.Local.Tool 2.0.0-alpha.1

H073.Local.Tool

Command-line tools for H073.Local, the .NET localization library.

This is not a library you reference from code. It installs a program called hxloc onto your machine, which you run from a terminal or a CI job. It never ends up inside your application.

dotnet tool install -g H073.Local.Tool --prerelease

It does two things: check your translations for problems, and compile them into the compact binary format for shipping.

hxloc check — find broken translations before you ship

hxloc check ./Localization

Reference: _master

  de/ui
    error  'welcome' drops placeholder(s) {name} — they render as nothing
    error  'welcome' uses unknown placeholder(s) {player} — they render literally
    error  missing key 'menu.settings'

  pl/ui
    warn   'files' has no "few", "many" form(s); pl needs "one", "few", "many", "other"
    warn   key 'extra' is not in the reference

3 error(s), 2 warning(s).

Why you need this

The library reads a folder of JSON files, one folder per language. Nothing anywhere declares which keys are supposed to exist — each file simply lists what it happens to contain. So if English is missing a key that German has, no error is raised anywhere. At runtime the fallback language quietly covers for it, and the missing-key log only ever sees keys that something actually asked for. A key on a screen nobody opened during testing stays invisible until a user finds it.

hxloc check is the only thing that catches that before release.

What it reports

The reference

Everything is compared against one catalogue. By default that is the _master folder if you have one, otherwise the language with the most keys. Override it:

hxloc check ./Localization --reference en

Options

In CI

The command exits with code 1 when it finds errors, so it fails a build:

- run: dotnet tool install -g H073.Local.Tool --prerelease
- run: hxloc check ./Localization

hxloc compile — build the binary format

hxloc compile ./Localization ./Localization.compiled

  de/ui                          412 keys      18,204 →     14,880 bytes
  en/ui                          412 keys      17,993 →     14,612 bytes

2 catalogue(s) → ./Localization.compiled   29,492 bytes, 82% of the JSON

It walks every language folder and turns each .json into a .bin, preserving the layout:

Localization/                     Localization.compiled/
├── _master/ui.json      →        ├── _master/ui.bin
├── de/ui.json           →        ├── de/ui.bin
└── en/ui.json           →        └── en/ui.bin

Ship the compiled folder and point Loc3Source at it. The JSON stays in source control and out of your package.

Run it as part of the build

<Target Name="CompileLocalization" BeforeTargets="Build"
        Condition="'$(Configuration)' == 'Release'">
  <Exec Command="hxloc compile ./Localization ./Localization.compiled" />
</Target>

This belongs in the build, not in your application. Compiling at startup would ship the JSON as well and pay the conversion cost on every launch — strictly worse than reading the JSON directly with JsonSource.

Options

What the compiler refuses to emit

Anything a reader could misinterpret fails the build instead: two keys whose hashes collide, a duplicate key, duplicate labels within one entry, a value over the format's limits, or a labelled entry with no category. All of them name the offending key.

Exit codes

Help

hxloc --help
hxloc --version

For the file format, the JSON layout and the library itself, see the H073.Local documentation.

Licence

Apache-2.0