Main menu

Machine translation

Automatically translate your Loco project

Loco's "bot" system provides integration points for automatically translating your content via external providers. Look out for the :robot icon: in various places around your dashboard.

We support established translation APIs and the latest generation of AI language models as listed below. The process is roughly the same for all of them. Get started with: How to add and run a translation bot.

Supported providers

The following third parties are supported on a "bring your own key" basis. We don't charge you for using these services, but some integration points require a paid Loco plan.

Dedicated translation APIs:

General purpose AI models:

See the linked pages for information on each provider. What follows is general information for all translation services.

Adding a translation bot

Wherever you see the :robot icon: you can view and manage your bots. The general approach to adding a new bot is as follows:

  1. Click "New bot" from the Bots tab on your dashboard;
  2. Configure its specific options and optionally share it;
  3. It's now ready to run manually or automatically on any project.

Sharing bots with your team

You can create bots for your own private use, or share them with your team. This is done from the individual bot configuration where you entered your API key. Sharing a bot doesn't provide elevated access to Loco. Translating content via a shared bot still requires permission to edit the target language.

Shared bots don't expose any secret credentials to their operator. However, bot usage can result in charges from the service provider, so we recommend you don't share a bot with anyone who you wouldn't also give your API key. See key security for advice.

Running your bots (translating)

There are several ways to run a translation bot:

  1. Using the suggest feature from the translation editor.
  2. Translating a project on demand from the dashboard.
  3. Translating only selected assets from the project "Manage" list.
  4. Scheduling a task to run automatically when new content needs translating.

1. Suggestions

Pressing Ctrl J from the translation editor (or clicking the :robot button: by the text field) opens a modal window with suggestions for translating the current item. This is the simplest way to test your bot without committing any changes.

Clicking a suggestion will copy it into the editor without saving it. If you see multiple suggestions, you can press 1, 2, etc.. as a keyboard shortcut for selecting your preferred suggestion.

All bots available in the current scope will be queried for suggestions, so be aware that using this feature may result in charges from multiple providers.

2. Translating a project on demand

You can find your bots listed under the Bots tab of your team and project dashboards; look for the :robot icon:. The list will include your own bots, plus any shared bots that are accessible to you.

Clicking the list entry will bring up a dialogue for running the bot manually. Configure as appropriate and run when ready.

  • Filter by tag:
    If your project has tags, you can reduce the list of sources to translate by entering them here. No tags, means all assets will be considered.

  • Filter by status:
    The most common use case is to translate all untranslated items, but you can select any other status here.

  • Target state:
    Modified translations will move to your selected target state. The default here is to mark translated items as "translated", but you could choose a flag to indicate the need for human review (e.g. "provisional").

Note that unchanged translations will NOT be flagged when a bot is run manually. This makes it easier to see what was changed.

3. Translating selected assets

Selecting assets in the "Manage" tab reveals a menu of batch processing actions above the list. This includes the :robot icon:. It works similarly to the ad hoc translation process above, except only on the selected assets. This is useful for translating a more specific selection of items that may not be filterable by tags or translation states.

4. Running in the background

Members of Pro account teams can schedule bots to run whenever changes are made to a project; for example whenever there are new untranslated items in a particular locale. This is done by adding a background task.

  • From the "Run bot" dialogue (explained above) switch to the Scheduled tab.
  • Click the :add icon: where it says "New task".
  • Choose a project and a running schedule (frequency).
  • Configure the translation task as per the on demand process.
  • Confirm "Add task" and the bot will be queued to run on your schedule.

Frequency:
This is the time between automatic translation runs. For example, A daily or hourly schedule will translate your project no more often than once per day, or once per hour. If there's nothing to translate, the task will wait until there is.

Background tasks are only triggered to run when changes are made to a project, so a continuous task doesn't mean it's continuously doing work. It will run as soon as possible after changes are detected.

Tasks are queued, so a continuous schedule may run a minute or two after changes are detected. You'll be notified via the relevant project alerts when a bot has made changes.

All translations processed in the background will move to the target state, even if the translation is unchanged. This is to avoid running up costs through repeated translation of the same text.

Language support

Traditional translation APIs are usually limited to some extent in the languages they support. Loco attempts to find the most appropriate match for your project locales, but will always attempt translation regardless. We allow APIs to return an error if a language pair is not supported.

You may find that your language works, but your particular region or dialect is wrong. For example: translating into Brazilian Portuguese may produce European Portuguese. This is likely to be because the service supports only the language code "pt" and not "pt-BR".

Loco project locales have a tone/formality setting, which you can modify if you have Developer permissions. This property is reserved for third party APIs that support it. Check the capabilities of your preferred vendor to see if it can be used.

Note that general purpose LLMs may not publish an official list of supported languages, but could (depending on the model) be capable of a much wider range than most traditional APIs. However, as with all generative AI models, they can't absolutely guarantee to produce what you've asked for.

Formatted strings

Most translation providers handle simple formatted strings quite well. For example the "%s" pattern in the string "Hello %s, how are you?" is left intact by all the providers we support. Whether the translation system understands it's a placeholder, or just treats it as punctuation, this is more of a bonus than expected behaviour.

Named placeholders are much less reliable. The ICU formatted string "Hello {name}" gets translated (into French) as "Hello {nom}" by all our supported providers. Using less natural variables like "Hello {NAME_OF_USER}" gives mixed results, but in general you can expect automatic translation of this kind of text to require human review.

Placeholder protection

Loco's bot configuration (for some providers) has an option to protect placeholders in formatted strings. When you enable this option, Loco sends the source text with a less translatable placeholder, and then substitutes the original pattern back into the translation. This relies on undocumented capabilities of the APIs, but we've seen some good results.

Notes and limitations:

  • Placeholder protection is only performed when the asset's format property is set. See String formatting
  • Escape sequences in literal parts of a formatted string such as %% (literal percent) or '{literal}' (ICU braces) are not substituted. This is probably desirable, but always check translations for valid syntax.
  • Translatable text inside nested ICU patterns won't be translatable if their parent element is protected. e.g. Hello {num,plural,one{sir}other{gentlemen}} will protect "num" and "plural", but "sir" and "gentlemen" won't be translated either.
  • This option isn't implemented for our general purpose LLM providers, as it doesn't seem to be needed.

Finally it should be noted that any placeholder potentially subtracts meaning and/or grammatical data from a sentence, so expect the quality of formatted translations to be impacted whether you have placeholder protection enabled or not.

Third party services are subject to their individual terms of use and may incur fees from the provider. Please refer to your service provider's documentation for pricing and terms.

Your usage of translation providers is a legal arrangement between you (the end user of Loco) and the service provider in question. Loco is not party to this agreement, except to the extent that we are sending traffic to their servers and will abide by their terms of use.

We are not reselling access to third party APIs. We provide API integration points, and our software (in some capacities) requires a paid subscription. Billing for these services will come directly from your provider, and will be based on the volume of translation you have configured our software to perform.

We are not responsible for what you do with the translations you store in Loco, whether obtained from machines or humans. Check the attribution requirements of any third party content you use.

Attribution

Content saved automatically into Loco is attributed to the translation service provider by way of a credit in the Loco project management view. Any edit will remove the attribution, but it will remain in the asset's revision history.

When downloading your translations and using them in your own software, you may be required to publicly show a similar attribution. We can't advise more specifically on this topic, but be sure to check the terms of your chosen provider and abide by them.

See also

Last updated by