One-off translations via API

Beta. Send a piece of text to the Localhero.ai API and get it back translated into the languages you ask for. The translation follows your project's glossary, style guide and tone of voice, the same as the translations in your pull requests. Nothing is saved: no key is created and no locale file changes. It is meant for text that lives outside your locale files, such as an email, a release note or a message your app generates.

curl -X POST https://api.localhero.ai/api/v1/projects/your-project-slug/suggest \
  -H "Authorization: Bearer $LOCALHERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_text": "Your trial ends in 3 days. Add a payment method to keep your translations running.",
    "reference_locale": "en",
    "target_locales": ["sv", "de"]
  }'

{
  "suggestions": {
    "sv": {
      "content": "Din provperiod tar slut om 3 dagar. Lägg till en betalningsmetod så att dina översättningar fortsätter att fungera.",
      "reasoning": "Natural trial notice; clear CTA; kept friendly UI tone"
    },
    "de": {
      "content": "Ihre Testversion endet in 3 Tagen. Fügen Sie eine Zahlungsmethode hinzu, damit Ihre Übersetzungen weiterlaufen.",
      "reasoning": "Natural warning tone; formal Sie implied; payment method = Zahlungsmethode"
    }
  },
  "credits_used": 2,
  "skipped": []
}

Authentication

Send an API key as a bearer token in the Authorization header. Get one from your account. It is the same kind of key the CLI and the GitHub Action use as LOCALHERO_API_KEY.

The project in the URL is your project's slug: the projectId in localhero.json. The key has to belong to the organization that owns the project.

Request

POST /api/v1/projects/:project_id/suggest with a JSON body.

Field	Required	Description
reference_text	Yes	The text to translate. Up to 10,000 characters.
reference_locale	Yes	The language reference_text is written in, such as en. It does not have to be the project's source language.
target_locales	No	The languages to translate into, such as ["sv", "de"]. Leave it out to get every language in the project except reference_locale.

Underscore codes such as pt_BR work too. The response is keyed by the code you sent.

Response

Field	Description
suggestions	One entry per translated language, keyed by locale. Each has content (the translation) and reasoning (a short note on the choices made).
credits_used	Credits charged for this request.
skipped	Languages left untranslated because the organization had no credits for them.

Errors come back as {"error": {"code": "...", "message": "..."}}.

Status	Code	When
401	invalid_api_key	The key is missing, wrong or revoked.
404	project_not_found	The key's organization has no project with that slug.
422	missing_parameters	reference_text or reference_locale is missing.
422	reference_text_too_long	reference_text is over 10,000 characters.
429	rate_limit_exceeded	More than 5,000 requests in five minutes with one key.

What the translation follows

The same project settings as the translations in your pull requests:

• Glossary terms that appear in the text
• The style guide, tone of voice and brand name
• Translation memory, built from the corrections your reviewers have made
• Existing translations in the project, as examples of voice and wording

Credits

Each target language is charged on its own: 1 credit per started 100 characters of reference_text. A 250-character text into three languages costs 9 credits, 3 per language. A language that fails is not charged. See pricing for what each plan includes.

The request needs an active plan or trial. Without one, every language comes back in skipped. If your credits run out partway and your plan doesn't allow going over its limit, the remaining languages come back in skipped too.

Limits during the beta

• The response comes when every language is done. Languages are translated one after another within the request. A long text into many languages can take a minute or more. Call it from a background job, not from a request a user is waiting on.
• An unknown code in target_locales is left out of suggestions without an error. So is a language where the translation itself fails. Compare the keys in suggestions with what you asked for.
• An unknown reference_locale returns a server error instead of a clear message.
• One text per request. Send separate requests for separate texts.
• Nothing is stored. Keep the translation yourself if you need it again. For strings that belong in your app, add them to your locale files and let the GitHub Action translate them in the pull request.
• The request and response may change while this is in beta.

The MCP server has the same feature as its translate_text tool, for when you want a quick translation from Claude or ChatGPT instead of from code.

Want to use it?

The API is in beta and we would like to hear what you want to use it for. Email hi@localhero.ai with what you want to translate and roughly how much. We'll help you get set up.