Introduction

The Intlfy API translates your JSON locale files using AI — preserving structure, key names, and interpolation variables. Repeated content in translation requests costs only 0.2%, while direct cache lookups by hash cost just 0.1%.

The base URL for all requests is https://api.intlfy.com. All endpoints accept and return JSON.

Authentication

All API requests must include your API key in the x-api-key header. Generate and manage your keys in the Panel.

curl -X POST https://api.intlfy.com/translations \
-H "Content-Type: application/json" \
-H "x-api-key: sk_live_your_key_here" \
-d {'"content"': {'"hello"': '"world"'}, '"targetLanguages"': ["pt-BR"]}'

Keys are prefixed with sk_live_. Only active keys will be accepted.

Translate Endpoint

POST/translations

Translates a JSON content object into one or more target languages in a single request.

Note: Translation response times may vary depending on the AI provider's current load and the size/complexity of your content. Large files or deep nesting may take longer to process.

Limit: The combined size of content and context must not exceed 440 KB per request.

Cache Lookup

GET/translations?hash=...&targetLanguage=...

Check if a translation already exists in our cache using its unique hash. This allows you to retrieve translations without sending the full source content again.

curl -H "x-api-key: your_key" \
"https://api.intlfy.com/translations?hash=db72...fc10&targetLanguage=pt-BR"

Request Schema

{
  // Required
  "content": object,          // JSON object to translate
  "targetLanguages": string[], // e.g. ["pt-BR", "es", "fr"]

  // Optional
  "sourceLanguage": string,   // default: "auto"
  "context": string,          // Optional global context
  "protectedPatterns": [
    { "begin": string, "end": string }
  ]
}

contentobjectrequired

The JSON locale object to translate. Nested objects are fully supported. Only string values are translated — keys are preserved. Combined with context, size is limited to 480 KB.

targetLanguagesstring[]required

Array of BCP-47 language tags to translate into. e.g. "pt-BR", "es", "zh-Hans", "ja".

sourceLanguagestringoptional

BCP-47 tag of the source language. Defaults to "auto" (automatic detection).

contextstringoptional

Global context, instructions or description for the translation (e.g. "Formal tone", "Technical documentation", "E-commerce platform").

protectedPatternsarrayoptional

Array of { begin, end } objects defining token boundaries to protect from translation. Note: HTML tags and content in single `{}` or double `{{}}` curly braces are automatically ignored and don't need to be specified here.

Example Request

curl -X POST https://api.intlfy.com/translations \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "welcome": "Hello, {name}!",
      "logout": "Sign out",
      "errors": {
        "required": "This field is required"
      }
    },
    "targetLanguages": ["pt-BR", "es"],
    "sourceLanguage": "en"
  }'

Response Schema

{
  "translations": {
    "[lang]": object  // translated JSON matching input structure
  },
  "cached": string[], // languages served from cache
  "contentHash": string
}

Example Response

{
  "translations": {
    "pt-BR": {
      "welcome": "Olá, {{name}}!",
      "logout": "Sair",
      "errors": {
        "required": "Este campo é obrigatório"
      }
    },
    "es": {
      "welcome": "¡Hola, {{name}}!",
      "logout": "Cerrar sesión",
      "errors": {
        "required": "Este campo es obligatorio"
      }
    }
  },
  "cached": [],
  "contentHash": "a3f8bc..."
}

Caching

Translations are cached by contentHash — a deterministic hash of the source content and target language. The cache TTL is 30 days, reset on every access.

Cache Miss

100%

Full AI processing cost.

POST Hit

0.2%

Repeated content in translation.

GET Hit

0.1%

Direct lookup by hash.

The cached array in the response lists which languages were served from cache. Each cache hit resets the 30-day expiry.

Error Codes

400

Bad Request

Missing required fields or malformed JSON body.

401

Unauthorized

Missing or invalid x-api-key header.

403

Forbidden

The API key is inactive or the application has been deleted.

413

Payload Too Large

The combined size of content and context exceeds the 480 KB limit.

500

Internal Server Error

An unexpected error occurred during translation. Retrying usually resolves it.