Localization Best Practices for Managed Packages

Question

I have worked with Custom Labels in Managed packages forever but never had to refactor an existing app to be localizable (I18N) for multiple languages. So in this question I would like to hear from other ISV partners that have internationalized their app on how they did it:

1. How do you decide what becomes a label and what does not?
2. How do you fight redundancy among your labels without inventing complicated dependencies?
3. How do you modularize your labels and version them in GIT? Or just a single messy file?
4. Which tools do you use for translation? Are there external tools that simplify handling and actual translation?
5. Can I allow or restrict subscribers to adjust my translations?

Answer 1

This is from my perspective, covering the packages we have:

1. Any information that can be presented to a user, through the UI or some other API, needs to be localized. As such we basically localize everything.
   • Many items support their own localization without the use of custom labels. Examples are screen flow text, custom tabs, objects, fields etc.
   • We have language-specific email template variants (we suffix the template with the locale and have code that selects the correct variant based on the recipient's locale, not the current user's locale). Where we cannot auto-select a different variant we provide a single template with sections for each language.
   • We localize not just UI furniture, but also exception messages since these could be presented to a user.
   • We encourage inclusion of contextual information in such messages via use of "mailmerge" (using String.format).
2. We do not worry about apparent "redundancy" across labels; our rationale is that while in English we may phrase something the same way in two or more contexts, that may not be the same across all languages. As such we do find we have some apparent repetition in our labels, but the short description covers the context of use to help the translator better understand how to translate the message text.
3. All our labels are in a single CustomLabels XML file per package and we maintain the label content in alphabetical order by API name; all new labels are added to the XML by hand, never through the Salesforce UI and then pulled.
   • We use a prefix on each label API name to define the "module" to which it belongs.
   • We also include "categories" to "group" labels together with that as well, plus a category that indicates that the label requires mailmerge.
   • For mailmerge cases the short description covers what the insertions represent.
4. Where possible we export to XLF and provide that to our translation service (we don't do the translation ourselves). They maintain a catalog of what they already translated and look out for new or modified entries to translate each time. I don't know what tooling they use.
5. AFAIK you cannot stop a subscriber from providing translations, assuming they have admin capability and access to the translation workbench.

Answer 2

Our core of our app is a JavaScript SPA that's used in Hybrid containers, so we're not using LWC etc. for the UI, but we still leverage custom labels:

1. How do you decide what becomes a label and what does not?

Simple rule: every single text string in the UI is a label enabling localization

2. How do you fight redundancy among your labels without inventing complicated dependencies?

They're grouped using category by functional area of the app, but our app is pretty specific in domain so there's no real clash as such of label usage

3. How do you modularize your labels and version them in GIT? Or just a single messy file?

One big file, as @PhilW says - we add them all by hand, never through the UI. Pull the file seems to randomly mess the order around. Tend to add them always at the bottom to simplify merges etc.

4. Which tools do you use for translation? Are there external tools that simplify handling and actual translation?

We simply send CSV files out to third parties and get the responses back, though we don't actually package translations and just distribute them as part of implementation.

5. Can I allow or restrict subscribers to adjust my translations?

I don't believe so, but there's a benefit in not doing this - even if all your customers use the same language, they may want to re-label things in the app, this provides a simple mechanism for them to put their own spin on your solution.

Answer 3

For the Geopointe app, we use the Localize JS service (https://localizejs.com/). This has all translation happen on the client side in real time. It allowed us to support new languages very quickly.

This is a nice solution IF you have control over injecting JavaScript into the UI (like a full page app).

We had to use Custom Labels for a few things like Tab Names and a couple other things, but it was minimal.