Localisation docs for engineers

The Localisation Team collaborates with Engineering through two main workflows:

1. A localisation-driven workflow (aka Figma/Phrase workflow), and
2. An engineering-driven workflow

The localisation-driven workflow is preferred. It's better than the engineering-driven workflow because it’s…

• Faster. It’s typically takes two fewer weeks.
• More efficient. It saves engineers' time.
• Higher quality. The translation output is better.

Phrase Strings is our product localisation management system. To learn about it, check out the Phrase Strings section.

---

Localisation-driven workflow#

(aka Figma/Phrase workflow)

In this workflow, the Localisation team creates keys and adds them to Phrase when the designs are finalised. This removes the dependency on engineers to start localising content. This head-start for localisation avoids a process bottleneck. Once the keys are in Phrase, engineers can code their minimum viable product (MVP). In the meantime, localisation kicks off the translation process. Usually, unless it’s a rush job, all keys will be created and fully localised by the time engineers start building.

Steps of the workflow#

1. Notify localisation. The product or content designer tells the localisation manager when the design and content is almost done and the MVP is signed-off on.
2. Create a key. The localisation manager uses the key naming conventions below to create the key names. Then, they replace the text layer in Figma with the key.
3. Document the key. The localisation manager adds the tag name and localisation highlights in Figma. The tag names link to Phrase and are a reference to share keys between teams. The highlights provide more details about each key and context about the project.
4. Finalise the key. Once the keys are in Phrase, the Localisation Manager finalises them by checking and updating the placeholders and pluralisation.
5. Assign translation. The Localisation Manager assigns the job to the Specialists or freelancers. Please note that engineers should NOT create jobs in Phrase.
6. Put keys into Github. Once localisation is complete and has been confirmed by the Localisation Specialist, engineers can move the keys as needed. Please note the localisation manager doesn’t support moving the keys to Github once localisation is complete.

Troubleshooting#

If you suspect there's a missing key, do the following:

• Double-check the localisation highlights on Figma
• Review the keys tagged with the project tag on Phrase
• If you’re still not able to find it, tag the relevant Localisation Manager on Figma or flag it on the #localisation-team Slack channel

Engineering-driven workflow#

The main difference between this workflow and the other is that engineers create Phrase keys and request translations. This means localisation has a shorter timeframe to do the translations. We aren’t able to guarantee completion within the engineering timelines, unless we’ve been given sufficient heads-up. If your team uses the engineering-driven workflow, follow the instructions below to create and name keys and tags.

Steps of the workflow#

1. Content approval is coordinated by the engineer. If multiple engineers work on the same feature that needs localisation, please consolidate the keys and minimise the number of requests.
2. Engineers push the keys to the relevant Phrase project either automatically or manually via the Phrase Strings UI.
3. Documentation is done by the engineer. They must tag the keys and add screenshots for each of them. If no screenshot exists, add a description.
4. Translation request is made by the engineer via the request form.
5. Key verification is done by the Localisation Manager. Once they’re verified, they assign the job to the Localisation Specialists and/or freelancers. Engineers should NOT create jobs in Phrase.
6. Completion notification is given by the Localisation Manager via Jira/Slack once all the strings have been localised. Engineers then move the localised keys to their intended location.

Teams that use this workflow#

We currently don't have a full overview over which teams use which workflow. A general rule of thumb is that if there's a Figma file, the Localisation-driven workflow should be applied. In this scenario, it will likely be the Product Designer or Content Designer who places the request with Localisation. If there's no Figma file, the Engineer-driven workflow should be applied, and you as the Engineer will have to place the request.

Key creation#

A key is basically an ID for a string of content. A string is the actual content seen by the user. Keys can be either semantic or contextual.

If it’s a semantic key, the key’s name is identical to its value/string. For example, if the string says, “Enter your name” the key would be called “Enter your name”.

If it’s a contextual key it describes where the key appears, what it is, and what it does. For example, a contextual key for “Enter your name” might be called “create_account.enter_name.title”.

Android keys#

To create contextual keys follow either one of these structures: feature_flow_component or where_whatItDoes.whatItIs

• Each part is separated with an underscore (_)
• When an element has several words, use capital letters to separate them
• If the key appears several layers down (e.g. Sales > Refund disputes > Dispute modal), only reference the top and the bottom layer (e.g. sales.dispute_modal…)
• For generic, reusable content use the word “common”, e.g. common_continue_button

For a key used on the order page on the "place order" CTA, the key would be named as follows: orderPage_placeOrder_CTA

Keys for everything else#

To create contextual keys follow either one of these structures: feature.flow.component or where.what_it_does.what_it_is

• Each part is separated with a full stop (.)
• When an element has several words, use underscores (_) to separate them
• If the key appears several layers down (e.g. Sales > Refund disputes > Dispute modal), only reference the top and the bottom layer (e.g. sales.dispute_modal…)
• For generic, reusable content use the word “common”, e.g. common.continue.button

For a key used on the order page on the "place order" CTA, the key would be named as follows: order_page.place_order.cta

Tag creation#

When you create keys, tag them appropriately to help findability. Normally, you can just use the project name or Jira ticket as the tag. On Consumer you might need to add an additional tag as follows:

• rb is used in the Ruby code

• scala is used in Scala code

• js is used in the old Angular web app

• jsx is used in the React web app

• next is used in CWA

• consumer-android is used in Android

NOTE: Make sure you use the right tags so it will be pulled.