Guidance for FHIR IG Creation
0.1.0 - CI Build
Guidance for FHIR IG Creation, published by HL7 International - FHIR Management Group. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/FHIR/ig-guidance/ and changes regularly. See the Directory of published versions
Audience. This page is for the people who maintain a language in the FHIR tooling, typically an HL7 affiliate or whoever is listed for that language in the editors file. IG authors do not need it: if your language is already supported, translate your IG as described on the other pages, and if it is missing, contact your affiliate rather than opening the language yourself.
The publisher's own text, the table headings, labels and validator messages described in Publisher-generated text, is translated in the FHIR core Java library. If a language is not in the list yet, someone has to open it up: register the language, generate the empty translation files, and submit them so the language ships with the next release. This page walks through that.
All paths below are inside the org.hl7.fhir.core repository,
under org.hl7.fhir.utilities/src/main/resources/ unless stated otherwise.
org.hl7.fhir.core that you can build.sv; add a region with an underscore if the region matters, as in pt_BR.Add a line to translations-control.ini under [languages]. The value is the number of plural forms in the
language, which decides how many msgstr[n] slots each plural message gets in the PO file.
[languages]
de=2
es=3
ja=1
...
sv=2
For reference, the languages already registered use 1 (ja, zh, ko), 2 (de, fr, nl, pt, uz, sv), 3 (es, ru, lt) and 6 (ar). The CLDR plural rules list the categories for every language.
languages.csv gives the name of every supported language in every supported language. The publisher uses
it to label the language switcher in a multilingual IG. Add a column for the new language, with the name of
each existing language in the new language, and add a row for the new language, with its name in each
existing language.
language,en,de,...,sv
en,English,Englisch,...,Engelska
...
sv,Swedish,Schwedisch,...,Svenska
If a cell is left empty the publisher falls back to the display from the FHIR languages value set, so this step is not blocking, but the switcher looks better with it.
The generator writes translations into Java properties files, but it reads the first line of each file to learn the plural keywords for the language. So the files must exist before the first run, holding only that header:
Messages_sv.properties
# InstanceValidator = one,other
rendering-phrases_sv.properties
# Rendering = one,other
The keywords after = are the plural categories for the language, in order. Their number must match the
count in translations-control.ini, and their order defines which msgstr[n] in the PO file maps to which
category. Look at the header of an existing language with the same plural structure and copy it.
Add a line to source/editors.txt with the language code, your name and GitHub handle. This is who gets
contacted about that language.
Build the validator CLI once:
mvn package -DskipTests --projects org.hl7.fhir.validation.cli --also-make
Then run the language regeneration command, giving it the three repository paths:
java -jar org.hl7.fhir.validation.cli/target/org.hl7.fhir.validation.cli-<version>-SNAPSHOT.jar lang-regen ^
<path to org.hl7.fhir.core> ^
<path to fhir-ig-publisher> ^
<path to fhirsmith>
The repository root has a regenerate-po.bat that wraps this; edit its three paths to match your machine.
The command first checks that every message constant in the Java code has an English string and vice versa, scanning all three repositories. If that check fails it prints the errors and stops without generating anything. That means the code is out of sync, not that your language is wrong; ask on the FHIR Zulip if it happens on a clean checkout.
When the check passes, it regenerates every language, including yours. You should now have two new files:
source/rendering-phrases-sv.posource/validator-messages-sv.powith every English phrase as a msgid and an empty msgstr. The properties files stay header-only until
there are translations to put in them.
Commit and open a pull request against org.hl7.fhir.core with:
translations-control.inilanguages.csvMessages_sv.properties and rendering-phrases_sv.propertiessource/rendering-phrases-sv.po and source/validator-messages-sv.posource/editors.txtThe PO files can be empty or partly translated at this point. Once merged, the language exists in the next release and translation can proceed as described in Publisher-generated text. The project's Crowdin configuration is driven by the file names, so a new language's PO files are picked up there automatically.
Translate the PO files, then run lang-regen again. It merges your translations into the properties files
and preserves them on later runs, marking entries whose English changed as described under
Publisher-generated text.
You do not need a release to try your translations. Both the validator and the IG publisher accept the PO files at runtime:
java -jar validator_cli.jar ... -po-dir path/to/source
java -jar publisher.jar -ig . -po-dir path/to/source
-po <file> loads a single file. File names must follow the convention, validator-messages-sv.po or
rendering-phrases-sv.po, because the loader infers the bundle and locale from the name. Add
-po-stale-handling exclude to see English instead of outdated translations.
The Java code refers to messages by constant, for example ABSTRACT_CODE_NOT_ALLOWED, defined in
I18nConstants for validator messages and RenderingI18nContext for rendering phrases. At runtime it looks
the constant up in a Java ResourceBundle: Messages.properties or rendering-phrases.properties for
English, and Messages_<locale>.properties or rendering-phrases_<locale>.properties for other languages.
If no bundle exists for the locale, the library logs that the locale is not supported and falls back to English.
The PO files under source/ are the master copy for translators. The generator reconciles each language's PO
file against the English properties file: it adds entries for new phrases, removes entries for phrases that no
longer exist, marks translations whose English changed as outdated, sorts by id, and gives duplicated English
strings a msgctxt so translation tools keep them apart. It then flattens the PO into the language's
properties file.
Plural messages are stored in the English properties file as two keys, <id>_one and <id>_other, and in
the PO file as one entry with a msgstr[n] per plural form. When writing the properties file back, msgstr[n]
becomes <id>_<keyword>, taking the keyword from position n of the header line. At runtime the library uses
ICU plural rules for the locale to pick the keyword for a given number, so the header keywords must be the CLDR
category names for that language.
The runtime override flags use the same reconciliation code, so a PO file from a newer or older checkout still lines up with the installed jar.