Developer Workflow

Why

In order to deliver a better developer experience, YAML files have been bundled into the main applications (lapis and SPA). This also means the applications always have a local fallback if ever S3 goes down.

The following page provides an overview of the intended workflow for developers to support localisation.

1. Develop your feature in the relevant application

It is intended that you can build your feature without needing the localisation repository. You may also completely omit defaultValue from your code.

2. Maintaining keys

2.1. Creating keys

Create your key in the relevant YAML file. Make a note of the reference location. For example in common.yml:

values:
  disabled: Disabled

The key reference would be common:values.disabled.

2.2. Updating keys

Text changes for keys are done in the YAML. If text changes in YAML, it will need to be reviewed and retranslated when committed to the localisation repository.

Refactored key structure will also require translation, as technically these would be considered new keys. Ensure that your YAML refactor is necessary before committing.

2.3. Deleting keys

As straightforward as it sounds. Delete your keys in the local YAML.

Note that keys will not actually be removed until you remove them from the localisation repository. Doing so will trigger an automation on Lokalise that automatically prunes the keys for you. This won’t affect production until the next release.

3. Using keys

Using keys is straightforward. Recall our key that we set up earlier in common:values.disabled.

Using this key in SPA:

const tCommonValues = useScope('common:values')
<Text>
  {tCommonValues('disabled')}
</Text>

In lapis there is a t function in the global namespace:

\t('common:values.disabled')

Or for database strings, in your Eloquent Model:

use Lapis\Domain\Core\Database\HasTranslatedNameColumnTrait;
class EloquentThing extends Model
{
    use HasTranslatedNameColumnTrait;
    ...
}

Read more about database localisation here

4. Linting

To ensure that you haven’t used any missing keys, you should lint your projects.

In Lapis:

docker compose run --rm yarn i18nLint

And in SPA:

docker compose run --rm local yarn i18nLint

5. Reflect the new keys into the localisation repository

After you have merged your feature and you are ready to release it, the localistion repo needs to be updated with a merge request containing the changes.

An MR will be automatically generated and assigned to all members of the team containing a merged YML between both repositories. This MR can be used to quickly update the localisation repo with your changes as you do things in lapis/SPA.

The keys added to Lokalise will automatically flow into to the development S3 bucket. This may take several minutes.

6. Review your strings in Lokalise

Since there are a limited number of seats, you will need to log in to Lokalise using the shared engineering account. This is stored in the Engineering Team 1Password vault as Lokalise Shared.

You should verify that:

• there are no spelling/grammar mistakes
• important words like intelliHR are spelled correctly following the guidelines
• english UK/US exist and have the correct localisation of their sentences
• all placeholders (including escaped placeholders) are in the universal placeholder format: [%1$s:personName]
• all placeholders are named the same thing, even in other languages for example, personName
• formatting hasn’t been broken

If needed, review translations on dev stack (translations may take several minutes to appear).

7. Translation Lifecycle

For a deep dive on how your translated makes it way into Production via automation triggers please check out: Translation Life Cycle