Guidance for FHIR IG Creation
0.1.0 - CI Build International flag

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

Publisher-generated Text

Table headings, labels, hints and validator messages are generated by the Java tooling the publisher is built on. You cannot translate these in your IG. They are translated once, in the tooling, and ship with each publisher release.

What to do

  • Check whether your language is already covered. The coverage per language is published on the FHIR core GitHub page.
  • If it is missing or incomplete, contribute. The master copy of the translations is a set of PO files in the FHIR core repository, and editors.txt lists who to contact for each existing translation.
  • If your language is not there at all, ask your HL7 affiliate to open it. The steps for doing so are on Adding a new language, which is written for language maintainers.
  • Update your publisher after the contribution is released, or try your PO files immediately with the -po-dir flag described on that page.

Contributing translations

Keep the following in mind:

  • There is only one set of translations per language (or region). Contributors have to collaborate. Disputes are resolved by the relevant HL7 affiliate if there is one.
  • The set of phrases covers both text rendered into IGs and validator error messages.
  • The set grows constantly as the publisher is developed, and existing messages change.

Edit the PO files by hand, with software, or with AI followed by review, and submit a GitHub pull request.

How this works

Internally the Java code uses standard .properties files; the PO files are the translator-facing master copy.

The generated PO files have no header. Translation tools may add one, and it is ignored. Each file is a series of entries:

#: [MSG_ID]
#| [previous]
msgid "[english]"
msgstr "[translated]"
  • MSG_ID identifies the phrase in the Java code. Always present.
  • previous is the earlier English text, present only when the English has changed since the last translation. The generator also writes it into the leading comment as "when last translated was: …".
  • english is the phrase to translate. Always present.
  • translated is the existing translation. If the English text has changed since, it is prefixed with !!. Present but possibly blank.

A plural message, one that has a number of something associated with it, looks like this:

#: [MSG_ID]
msgid "[english]"
msgid_plural "[plural form in english]"
msgstr[0] ""
msgstr[1] ""

There is one msgstr[n] line per plural form declared at the top of the file. The msgid_plural gives the English plural to help translators see which words go with the count.