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

Setting up the IG

Before anything else, make sure the IG uses a template that supports languages. The template renders the language switcher, the translated tab names and table headings, and the notice on pages that have no translation. On a template without language support, none of that appears, whatever the IG declares. The language-aware base template is fhir2.base.template; the original fhir.base.template has no language support. See Template text.

With that in place, three IG parameters turn a single-language IG into a multilingual one. They go in the parameter list of the IG resource. With FSH, put them under parameters in sushi-config.yaml and SUSHI writes them into the IG resource for you.

Declare the default language

This is the language the IG is authored in. The default is en.

<parameter>
  <code value="i18n-default-lang"/>
  <value value="en"/>
</parameter>
{
  "code": "i18n-default-lang",
  "value": "en"
}
# sushi-config.yaml
parameters:
  i18n-default-lang: en

Declare the additional languages

One i18n-lang parameter per language. Use a language code, optionally with a region (for example pt-BR).

<parameter>
  <code value="i18n-lang"/>
  <value value="nl"/>
</parameter>
<parameter>
  <code value="i18n-lang"/>
  <value value="es"/>
</parameter>
{
  "code": "i18n-lang",
  "value": "nl"
},
{
  "code": "i18n-lang",
  "value": "es"
}
# sushi-config.yaml
parameters:
  i18n-lang:
    - nl
    - es

Say where the translations are

One translation-sources parameter per language. The folder must be under input, and its last segment must be exactly the language code. input/translations/{lang} is the usual choice.

<parameter>
  <code value="translation-sources"/>
  <value value="input/translations/nl"/>
</parameter>
<parameter>
  <code value="translation-sources"/>
  <value value="input/translations/es"/>
</parameter>
{
  "code": "translation-sources",
  "value": "input/translations/nl"
},
{
  "code": "translation-sources",
  "value": "input/translations/es"
}
# sushi-config.yaml
parameters:
  translation-sources:
    - input/translations/nl
    - input/translations/es

These folders hold both the resource translations and the translated narrative pages.

Build

Build the IG as normal. The publisher now generates translation files for your resources under translations/{lang}/. Continue with Translating resources.

How this works

  • i18n-default-lang sets the language of every generated resource and page that does not say otherwise.
  • Each i18n-lang adds a language to the set the publisher renders, and to the set it asks the terminology server for.
  • translation-sources folders are scanned on every build. Anything found there is applied on top of the source resources and pages before rendering.
  • Language packs use translation-supplements instead of translation-sources. The publisher treats the two the same way; the name records that the folder feeds CodeSystem supplements rather than a translated IG. See Language packs.