Localization

16min
﻿ mobile app supports multiple languages, significantly enhancing its market presence, user engagement, and overall success by appealing to a broader and more diverse audience. The real power of the  localization functionality lies in using a single  that can have multiple translations associated with the , the app respects the language setting of the device and renders the in that language if the corresponding language file is found or defaults to English. 
One jig in English & German
﻿
How it works
In  every property that accepts string-based values, e.g., field labels, can be localized. Wherever TextLocale pops up in IntelliSense, the value can be localized. The localization to the TextLocal is specified in the Translation folder in a file for each language. 
Only one translation file per language is used, For example, de.jigx for German will hold all the TextLocal id values for all s in the solution that must be localized.
﻿
IntelliSense for localized values
﻿
In the  under Profile>Settings>Language check that the setting Device is selected. This respects the settings of the device and if a matching language translation file is present in the solution the  will show in that language. 
Language Settings
﻿
﻿
Configuration
Configuring TextLocale is simple, and the translation can be: 
Static - Add localization to a  using a unique identifier with translated text
Dynamic - Add localization to a  using ICU Message definitions 
Static values - In the jig 
Invoke IntelliSense next to the property you want to translate.
Select TextLocale
Provide an id: for the value to be translated.
Optional: add the defaultMessage: property with a value. If there is no translation found for the active device's language, it will either fallback to the specified defaultMessage or if one is not specified, to English.
jig.jigx
children:
        - type: component.text-field
          instanceId: first_name 
          options:
            label: 
      # add the TextLocale id that will be used in the translation jigx file
              id: first_name
      # Specify a fallback if the lanaguage is not founnd on the device
              defaultMessage: First Name
children:
        - type: component.text-field
          instanceId: first_name 
          options:
            label: 
      # add the TextLocale id that will be used in the translation jigx file
              id: first_name
      # Specify a fallback if the lanaguage is not founnd on the device
              defaultMessage: First Name
﻿
Static values - In the translation file
Once the unique id has been set for the TextLocale, the file containing the translation needs to be configured: 
In  under the translations folder, create a new file. The file's name must be the ISO 6391-1 codes, for example, de.jigx for German, or fr.jigx for French. 
For multiple languages create a separate file per language required.
Add the unique identifiers (id) values specified in the , with the corresponding  translated text in the new file. 
If you using multiple languages, simply use the same unique identifiers (id) values in each language file and for static values ensure the translated text corresponds.
de.jigx
fr.jigx
cs.jigx
# add the id specified in the jig and the static Czech translated value
first_name: Jméno
# add the id specified in the jig and the static Czech translated value
first_name: Jméno
﻿
Dynamic values- In the jig
To set the TextLocal property dynamically 
Invoke IntelliSense next to the property you want to translate.
Select TextLocale
Provide an id:  and values properties. The values property requires context variables that will be used in the translation file.
Optional: add the defaultMessage: property with a value. If there is no translation found for the active device's language, it will either fallback to the specified defaultMessage or if one is not specified, to English.
jig.jigx
title: 
  id: jig-name
  defaultMessage: Example (Fallback)
type: jig.default

children:
  - type: component.entity
    options:
      children:
        - type: component.entity-field
          options:
            label: Localized Text (Static)
            value: 
              id: example-static
              defaultMessage: Good afternoon (Fallback)
        - type: component.entity-field
          options:
            label: Localized Text (Expression)
            value:
              id: example-dynamic
              values:
                name: [email protected]
                time: =$fromMillis($millis(),'[P]')
title: 
  id: jig-name
  defaultMessage: Example (Fallback)
type: jig.default

children:
  - type: component.entity
    options:
      children:
        - type: component.entity-field
          options:
            label: Localized Text (Static)
            value: 
              id: example-static
              defaultMessage: Good afternoon (Fallback)
        - type: component.entity-field
          options:
            label: Localized Text (Expression)
            value:
              id: example-dynamic
              values:
                name: =@ctx.user.displayName
                time: =$fromMillis($millis(),'[P]')
﻿
Dynamic values - In the translation file
Once the unique id has been set for the TextLocale, and the values configured the file containing the translation needs to be configured: 
For multiple languages create a separate file per language required.
Add the unique identifiers (id) values specified in the , with the corresponding  translated text in the new file. 
Add the context variable for the values specified in the . This can be values you add to the TextLocale: value option and ICU Message definitions. 
If you using multiple languages, simply use the same unique identifiers (id) values in each language file and for static values ensure the translated text corresponds.
localized-jig.jigx
de.jigx
greeting: '{time, select, am {Guten Morgen} pm {Guten Nachmittag} other {Hallo}} {name}'
greeting: '{time, select, am {Guten Morgen} pm {Guten Nachmittag} other {Hallo}} {name}'
﻿
Considerations for dynamic values
Dealing with spaces
The select clause is case-sensitive, avoid using spaces. 
YAML
# Working, notice there no spaces in the variable name
genus: '{title, select, hornet {Hornet (Vespa crabo)} house_wasp {House wasp} leafcutter_bee {Leafcutter bee}}'

# Not working due to spaces in the variable
genus: '{title, select, hornet {Hornet (Vespa crabo)} House wasp {House wasp} Leafcutter Bee {Leafcutter bee}}'

# Working, notice there no spaces in the variable name
genus: '{title, select, hornet {Hornet (Vespa crabo)} house_wasp {House wasp} leafcutter_bee {Leafcutter bee}}'

# Not working due to spaces in the variable
genus: '{title, select, hornet {Hornet (Vespa crabo)} House wasp {House wasp} Leafcutter Bee {Leafcutter bee}}'
﻿
If your datasource has spaces you can add an entry for the translation variable that removes the space. In the code example below an entry translation_string has been added to facilitate spaces.
datasource
jig-component
translation-file
value: 
  id: services_dropdown
  values: 
    translation_string: [email protected]_string
value: 
  id: services_dropdown
  values: 
    translation_string: =@ctx.inputs.inspection.translation_string
﻿
Be consistent when key names, for example, if you use underscore (_) then ensure all spaces are replaced with underscores.
Create a fallback for the variable. The fallback in the code example below is the other case. This means if the title variable is not cash_payment, the string Payment placeholder will be displayed.
fallback
cash_payment_title: '{title, select, cash_payment {Amount was paid in cash} other {Payment placeholder}}’
cash_payment_title: '{title, select, cash_payment {Amount was paid in cash} other {Payment placeholder}}’
﻿
Using conditions
When an expression or value of a property is configured with a condition, the condition needs to be defined in the translation file, see the code example below.
list.jigx
de.jigx (translation-file) 
title: Translate
type: jig.default

datasources:
  inspection-current: 
    type: datasource.static
    options:
      data:
        - id: 1
          name: John
          payment_status: Pending
        - id: 2
          name: Hannah
          payment_status: Paid  
        - id: 3
          name: Sarah
          payment_status: Pending
        - id: 4
          name: Hannah
          payment_status: Paid   

children:
  - type: component.list
    options:
      data: [email protected]-current
      maximumItemsToRender: 8
      item: 
        type: component.list-item
        options:
          title: [email protected]
          description: [email protected]_status = 'Pending' ? 'Pending payment':'Paid'
          subtitle: 
# Add an id to be used in the translation file 
            id: payment_status
# The default message is a fallback to English if the language is not found            
            defaultMessage: [email protected]_status = 'Pending' ? 'Pending payment':'Paid'
# Add values to be used in the condition in the translation file            
            values:
              status: [email protected]_status
title: Translate
type: jig.default

datasources:
  inspection-current: 
    type: datasource.static
    options:
      data:
        - id: 1
          name: John
          payment_status: Pending
        - id: 2
          name: Hannah
          payment_status: Paid  
        - id: 3
          name: Sarah
          payment_status: Pending
        - id: 4
          name: Hannah
          payment_status: Paid   

children:
  - type: component.list
    options:
      data: =@ctx.datasources.inspection-current
      maximumItemsToRender: 8
      item: 
        type: component.list-item
        options:
          title: =@ctx.current.item.name
          description: =@ctx.current.item.payment_status = 'Pending' ? 'Pending payment':'Paid'
          subtitle: 
# Add an id to be used in the translation file 
            id: payment_status
# The default message is a fallback to English if the language is not found            
            defaultMessage: =@ctx.current.item.payment_status = 'Pending' ? 'Pending payment':'Paid'
# Add values to be used in the condition in the translation file            
            values:
              status: =@ctx.current.item.payment_status
﻿
Examples and code snippets
The following examples with code snippets are provided:
﻿Localization (Translation)﻿﻿
﻿
Updated 03 Oct 2024
Did this page help you?
Deep links
Notifications