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 1 MB or ~110,000 tokens per request (whichever is hit first).

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: max 1 MB and ~110,000 tokens.

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

content + context exceeds 1 MB or ~110,000 tokens. Split into smaller chunks.

500

Internal Server Error

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