Localisation Best Practices

The base language should be Australian English (en_AU)

intelliHR is an Australian company and therefore uses Australian English as its base language. You should set this in your local spellchecker to avoid Americanisations in your text.

Keys should be sorted alphabetically

Ensure that you adhere to these patterns otherwise your MR will fail the pipeline linters. You can refer to the Sort Lines extension for a quick way to achieve this locally.

Keys should not be keywords

Do:

likesCatsTrue: I like cats
likesCatsFalse: I don't like cats.

Don’t:

true: I like cats.
false: I don't like cats.

Keys should be nested appropriately

Keep your keys simple and your nesting reasonable. This goes in both directions (too high level, too low level).

Shorter keys makes understanding and refactoring things easier.

Do:

alertMessages:
  actionEnabled: You can do this action
  actionDisabled: You can't do this action

Don’t:

can: You can do this action
ui.dialogues.alerts.messages.actions.state.disabled: You can't do this action

Keys should be semantic

Keys should be representative of the actual value stored in the string.

Do:

alertMessages:
  actionEnabled: You can do this action
  actionDisabled: You can't do this action

Don’t:

can: You can do this action
cant: You can't do this action

Strings should be generic

When creating your strings, try to be as generic as possible, so instead of The user {{user}} went to the {{place}}, use The user went to the store. For more general tips on how to structure your translations, use this guide from @intellihr/ui-components.

Strings should be deduplicated

It is common that some strings might be the same (you might have the same string on a button as in a dialog). intelliHR already has a common.yml file that encapsulates the most common cases.

For the rest of the duplicate strings, they should be deduplicated in all cases. As an example: buttons.services.deepl: DeepL and messages.deepl: DeepL would be considered duplicates.

If a duplicate string is used in multiple contexts (i.e. buttons and a messages), you should create a generic context (for example, common.values.deepl). This might seem counterintuitive, however it ensures minimal work is required from the localisation side to verify and translate strings, and prevents us from cluttering the Lokalise dashboard.

Strings should be indented properly

It is likely you will have strings that are too long to fit onto a single line. For this you will need to ensure that you have indented your multiline strings properly.

Do:

  singleLineString: I lied, I didn't go to the store.
  multiLineString: "
    The fact of the matter is, I didn't go to the store.
    You see, I am not a fan of people.
    "
  anotherMultiLineString:
    This is an example of a multiline string.<br/>
    Blah blah.

Don’t:

  singleLineString: I went to the store.
  multiLineString: "
  I went to the store to get some groceries.
  I couldn't find any eggs, though.
  "
  anotherMultiLineString: "
    I didn't think about it too much.
    I was under the weather, you see.
  "

Strings should use i18n placeholders and attributes

Unless working in specific areas of lapis, placeholder values should be wrapped in double curly braces, like so: {{}}. The placeholder name should match the attribute that you reference in code.

In sample.yml:

samplekeysection:
  mynewkey: This employee is {{employmentStatus}}.

And in your code:

const tFeature = useScope('sample:samplekeysection')
<sampleComponent>
  {tFeature('mynewkey', { employmentStatus: sampleEmployee.status })}   // => 'This employee is retired.'
</sampleComponent>

Where sampleEmployee.status might be retired/employed (full time)/employed (part time)/contracted etc.

Strings should use i18n pluralisation

You should never hard-code pluralisation in your feature. This increases application complexity, makes code hard to read, and in general is completely unnecessary. It’s also dangerous as different languages have different pluralisation systems.

Arabic, for example, has six different pluralisation cases. If you’d like to learn more, check out this article from Lingohub.

To pluralise, use an attribute (for example, { count: days }) and in your YML file include: example.days and example.days_plural keys. The i18n engine will take care of the rest for you. For example, if we wanted to count cats:

YML:

counts:
  cat: {{count}} cat
  cat_plural: {{count}} cats

TSX:

{tFeature('counts.cat', { count: 0 })}  // => '0 cats'
{tFeature('counts.cat', { count: 1 })}  // => '1 cat'
{tFeature('counts.cat', { count: 10 })} // => '10 cats'

To learn more about pluralisation in i18n, check out this page.