Localisation Best Practices
4 minute read
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.