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

Multilingual IGs

Every IG is authored in one primary language. Other languages are added by supplying translations, which the IG publisher merges into the published output. The primary language does not have to be English, although most existing IGs and the core FHIR specification use English.

This page is the starting point. It tells you what you need to do, in what order, and where each kind of text in the IG gets its translation from. The pages under it go into each step.

Quick start

  1. Declare the languages in the IG resource: the default language, the additional languages, and where the translation files live. See Setting up the IG.
  2. Build the IG. The publisher writes a translation file for every translatable resource into translations/{lang}/{format}/, in three formats (PO, XLIFF, JSON).
  3. Translate the resources. Pick one format, translate the generated file, and save it under input/translations/{lang}/. See Translating resources.
  4. Translate the pages. For each narrative page, write a translated copy under input/translations/{lang}/pagecontent/. See Translating narrative pages.
  5. Cover the content you do not own. Text from FHIR core, HL7 terminology, and other packages comes from language packs. Displays from external terminologies come from the terminology server. See Language packs and Terminology displays.
  6. Rebuild, review, repeat until the translations are complete. Existing translations are carried forward on every build, so only new or changed strings need attention.

Where the text comes from

The published IG contains text from six sources. You only translate the first two yourself. The rest are translated elsewhere, and your job is to reference the right packages and tools.

Text Who translates it How
Your resources (profiles, code systems, questionnaires, …) You Translation files in input/translations. See Translating resources.
Your narrative pages You Translated page files in input/translations. See Translating narrative pages.
Resources from FHIR core, THO and other packages you depend on The community for that language, or you A language pack you reference as a dependency, or translation files for those resources in your own IG. See Translating resources.
Displays from external terminologies (SNOMED CT, LOINC, …) The terminology authority The terminology server, which is asked for your languages. See Terminology displays.
Labels and messages generated by the publisher Contributors to the FHIR Java tooling Ships with each publisher release. See Publisher-generated text.
Text from the template The template maintainers PO files in the template. See Template text.

These pictures show the same six sources laid over the parts of a published IG:

IG language overview IG language overview - resource view IG language overview - valueset view


Template text

Tab names, table headings and the artifact index come from the template and are translated there, by the template's maintainers. As an IG author, use a language-aware template (see Setting up the IG) and report gaps to the template's maintainers. The maintainer side is on Template text.

Translation formats

The publisher accepts PO, XLIFF and its own JSON format. PO is preferred, and is required for the Java and template translations. See Translation formats.

Examples and references

  • Example language pack: hl7.fhir.r4.es
  • Example IG that uses a language pack, showing the translated display names: (to be added)