API Client Reference

Setup
AI Translation
- ai.translate
Projects
- projects.list
- projects.first
Files
Keys
Suggestions
Plural keys
- plural()
Import
- import.json
Export
- export.json
Formats
- formats.list
Screenshots
Glossary
Webhooks

Setup

Create a new instance of ApiClient and pass in your project token.

Arguments	Type	Description
options	`ApiClientOptions`	Api client options.

Returns	Type
`ApiClient`	`ApiClient`

import { ApiClient } from '@localazy/api-client';

const api = new ApiClient({ authToken: 'project-token' });

AI Translation

ai.translate(request[, config])

Translate provided items from the source language to the target language using Localazy AI and considering the provided context, project-defined style guide and glossary. Each translation request consumes Localazy credits from your account.

This endpoint is only available with the Owner's token or a Translation Token.

See: Localazy API Docs

Arguments	Type
request	`AiTranslateRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<AiTranslateResponse>`	`AiTranslateResponse`

Simple strings:

const response = await api.ai.translate({
  project: 'project-id', // or Project object
  from: 'en',
  to: 'cs',
  items: [
    {
      key: 'btn_submit',
      source: 'Submit',
      comment: 'Button label for form submission',
    },
    {
      key: 'welcome_message',
      source: 'Welcome back, %s!',
      lengthLimit: 50,
    },
  ],
});

Plural forms:

const response = await api.ai.translate({
  project: 'project-id', // or Project object
  from: 'en',
  to: 'cs',
  items: [
    {
      key: 'item_count',
      source: {
        one: '%d item',
        other: '%d items',
      },
    },
  ],
});

With fallback engine:

const response = await api.ai.translate({
  project: 'project-id', // or Project object
  from: 'en',
  to: 'de',
  fallback: 'deepl',
  items: [
    {
      source: 'Hello, world!',
    },
  ],
});

Projects

projects.list(request[, config])

List all projects.

See: Localazy API Docs

Arguments	Type	Description
request	`ProjectsListRequest`	Projects list request config.
config `optional`	`RequestConfig`	Request config.

Returns	Type
`Promise<Project[]>`	`Project`

const projects = await api.projects.list({
  organization: true,
  languages: true,
});

projects.first(request[, config])

First project.

At least one project must exist, otherwise an error is thrown.

See: Localazy API Docs

Arguments	Type	Description
request	`ProjectsListRequest`	Projects list request config.
config `optional`	`RequestConfig`	Request config.

Returns	Type
`Promise<Project>`	`Project`

const project = await api.projects.first({
  organization: true,
  languages: true,
});

Files

files.list(request[, config])

List all files in the project.

See: Localazy API Docs

Arguments	Type
request	`FilesListRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<File[]>`	`File`

const files = await api.files.list({
  project: 'project-id', // or Project object
});

files.first(request[, config])

First file in the project.

At least one file must exist, otherwise an error is thrown.

See: Localazy API Docs

Arguments	Type
request	`FilesListRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<File>`	`File`

const file = await api.files.first({
  project: 'project-id', // or Project object
});

files.listKeys(request[, config])

List all keys for the language in the file.

See: Localazy API Docs

Arguments	Type
request	`FileListKeysRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<Key[]>`	`Key`

import { Locales } from '@localazy/api-client';

const keys = await api.files.listKeys({
  project: 'project-id', // or Project object
  file: 'file-id', // or File object
  lang: Locales.ENGLISH,
});

files.listKeysPage(request[, config])

List all keys for the language in the file. Result is paginated.

See: Localazy API Docs

Arguments	Type
request	`FileListKeysRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<PaginatedKeys>`	`PaginatedKeys`

import { Locales } from '@localazy/api-client';

const keys = [];
let pageResult = { keys: [], next: '' };

do {
  pageResult = await api.files.listKeysPage({
    project: 'project-id', // or Project object
    file: 'file-id', // or File object
    lang: Locales.ENGLISH,
    next: pageResult.next,
  });
  keys.push(...pageResult.keys);
} while (pageResult.next);

files.getContents(request[, config])

Get the contents of the file.

See: Localazy API Docs

Arguments	Type
request	`FileGetContentRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<Blob>`	`Blob`

import { Locales } from '@localazy/api-client';

const blob = await api.files.getContents({
  project: 'project-id', // or Project object
  file: 'file-id', // or File object
  lang: Locales.ENGLISH,
});

Keys

keys.update(request[, config])

Update key.

See: Localazy API Docs

Arguments	Type
request	`KeyUpdateRequest`
config `optional`	`RequestConfig`

Returns
`Promise<void>`

await api.keys.update({
  project: 'project-id', // or Project object
  key: 'key-id', // or Key object
  deprecated: -1,
  hidden: false,
  comment: 'Comment.',
  limit: -1,
});

keys.delete(request[, config])

Delete key.

See: Localazy API Docs

Arguments	Type
request	`KeyDeleteRequest`
config `optional`	`RequestConfig`

Returns
`Promise<void>`

await api.keys.delete({
  project: 'project-id', // or Project object
  key: 'key-id', // or Key object
});

keys.deprecate(request[, config])

Deprecate keys.

Arguments	Type
request	`KeyDeprecateRequest`
config `optional`	`RequestConfig`

Returns
`Promise<void>`

await api.keys.deprecate({
  project: 'project-id', // or Project object
  phrases: ['key-id'], // or Key objects
});

keys.submitTranslation(request[, config])

Submit a translation for a single key in one target language.

value must match the key's form: a string for a singular key, an array of strings for an array key, or an object keyed by CLDR plural class for a plural key. lang accepts a locale code or Localazy's numeric language id, and is URL-escaped, so script-qualified locales such as zh#Hans are transmitted intact.

Plural values may use either the plain classes the write API expects ({ one: '1 item' }) or the @-prefixed form the read API returns ({ '@one': '1 item' }) — the prefix is stripped for you, so a value taken straight from files.listKeys() round-trips correctly.

Check result on the response. The API answers HTTP 200 with result: false and a message when a submission is deliberately not applied — the target is the project's source language, the project is momentarily locked by a running import, or the translation could not be stored. None of those reject the promise.

Arguments	Type
request	`KeySubmitTranslationRequest`
config `optional`	`RequestConfig`

Returns
`Promise<SubmitTranslationResponse>`

// singular key
await api.keys.submitTranslation({
  project: 'project-id', // or Project object
  key: 'key-id', // or Key object
  lang: 'cs',
  value: 'Uložit změny',
});

// plural key
await api.keys.submitTranslation({
  project: 'project-id',
  key: 'key-id',
  lang: 'cs',
  value: { one: '1 položka', few: '%d položky', other: '%d položek' },
});

keys.setTags(request[, config])

Add and/or remove tags on keys.

Removal is applied before addition, so a tag name present in both addTags and removeTags ends up added. Tag names that do not exist yet are created, subject to the project's 50-tag limit. At most 1000 keys may be passed per call; larger sets are rejected outright rather than truncated, and splitting them is the caller's responsibility.

See: Localazy API Docs

Arguments	Type
request	`KeySetTagsRequest`
config `optional`	`RequestConfig`

Returns
`Promise<BooleanResult>`

result reports that the request was processed, not that it changed anything: key ids that do not resolve within the project are skipped silently, and a call in which none of them resolve still answers true.

const { result } = await api.keys.setTags({
  project: 'project-id', // or Project object
  keys: ['key-id'], // or Key objects
  addTags: ['ui'],
  removeTags: ['legacy'],
});

keys.setPriority(request[, config])

Set the priority level on keys.

normal clears any priority currently set. At most 1000 keys may be passed per call; larger sets are rejected outright rather than truncated, and splitting them is the caller's responsibility.

See: Localazy API Docs

Arguments	Type
request	`KeySetPriorityRequest`
config `optional`	`RequestConfig`

Returns
`Promise<BooleanResult>`

const { result } = await api.keys.setPriority({
  project: 'project-id', // or Project object
  keys: ['key-id'], // or Key objects
  priority: 'high', // lowest | low | normal | high | highest
});

Suggestions

Per-key translation suggestions. Every response shares the same envelope:

enabled — whether the family could run at all. false means the feature is unavailable for the project, or the target language is the (possibly overridden) source language.
errors — soft failures keyed by engine name. A soft error never fails the request. The reserved key general covers failures belonging to no single engine, most commonly the key having no value in the source language.
items — one entry per source form: a singular key yields one entry, a plural or array key one per form.

Read those three deliberately: enabled: true with empty items means "ran, found nothing", which is a different answer from enabled: false.

In every method to is required and from is optional, defaulting to the project's source language. Both accept a locale code ('pt_BR') or Localazy's numeric language id (112).

suggestions.tm(request[, config])

Translation Memory (InTM) suggestions for a single key. Free and read-only.

Arguments	Type
request	`SuggestionsRequest`
config `optional`	`RequestConfig`

Returns
`Promise<TmSuggestionsResponse>`

const response = await api.suggestions.tm({
  project: 'project-id', // or Project object
  key: 'key-id', // or Key object
  to: 'cs',
});

suggestions.mt(request[, config])

Machine Translation suggestions for a single key.

Free to the caller, but a cache miss computes the translations live and meters them against the organization's machine translation fair-use quota.

Arguments	Type
request	`SuggestionsRequest`
config `optional`	`RequestConfig`

Returns
`Promise<MtSuggestionsResponse>`

const response = await api.suggestions.mt({
  project: 'project-id',
  key: 'key-id',
  to: 'cs',
  from: 'en', // optional source override
});

suggestions.ai(request[, config])

Localazy AI suggestions for a single key.

This method spends AI credits — that is why the underlying endpoint is a POST. Not to be confused with ai.translate, which translates arbitrary texts you supply rather than an existing key.

enabled requires both AI suggestions and Machine Translation to be switched on in the project's settings; producing results additionally requires an active paid MT tier, so enabled: true can still yield empty items with no error.

Arguments	Type
request	`SuggestionsRequest`
config `optional`	`RequestConfig`

Returns
`Promise<AiSuggestionsResponse>`

const response = await api.suggestions.ai({
  project: 'project-id',
  key: 'key-id',
  to: 'cs',
});

Plural keys

Plural values are objects keyed by CLDR plural class (zero, one, two, few, many, other). Which classes a language uses is defined by CLDR — English uses one/other, Czech one/few/many/other.

Two spellings exist, and which one you need depends on the endpoint:

Surface	Spelling	Example
`import.json` (write)	`@`-prefixed	`{ "@one": "%d item", "@other": "%d items" }`
`files.listKeys` (read)	`@`-prefixed	`{ "@one": "%d item", "@other": "%d items" }`
`keys.submitTranslation` (write)	plain, `@` also accepted	`{ "one": "%d item", "other": "%d items" }`

`plural()` — spell it once

plural() tags a value as a plural explicitly, so the client can render the right spelling for whichever endpoint receives it. This is the recommended way to author plural values by hand.

import { plural } from '@localazy/api-client';

// import  -> { "ITEMS": { "@one": "%d item", "@other": "%d items" } }
await api.import.json({
  project,
  json: { en: { ITEMS: plural({ one: '%d item', other: '%d items' }) } },
});

// submit  -> { "value": { "one": "%d élément", "other": "%d éléments" } }
await api.keys.submitTranslation({
  project,
  key,
  lang: 'fr',
  value: plural({ one: '%d élément', other: '%d éléments' }),
});

Arguments	Type
forms	`PluralValue`

Returns
`PluralMarker`

You always write plain CLDR classes; the @ prefix is added only where the wire format needs it. Raw objects keep working unchanged, so nothing existing breaks — plural() is opt-in.

Two things worth knowing:

The marker is resolved before the import payload is chunked, so it never reaches the wire. If you ever see __localazyPlural in a request body, a marker escaped unresolved — that is a bug, and it is deliberately a visible string rather than a symbol so it fails loudly instead of serializing to an empty object.
plural() only affects values you construct. A value read back from files.listKeys() is a plain @-prefixed object, and keys.submitTranslation normalises that on its own.

The `@` prefix is a disambiguator, not decoration

On import, the prefix is the only thing separating a plural key from a nested key group. Omitting it does not fail — it silently creates something else:

// ✅ ONE plural key `ITEMS` with classes one/other
await api.import.json({
  project,
  json: { en: { ITEMS: { '@one': '%d item', '@other': '%d items' } } },
});

// ❌ TWO nested singular keys `ITEMS.one` and `ITEMS.other`
await api.import.json({
  project,
  json: { en: { ITEMS: { one: '%d item', other: '%d items' } } },
});

Both are valid JSON and valid TypeScript, so nothing catches the second form — it is a legitimate way to declare nested keys, which is exactly why the client cannot add the prefix for you. Using plural() removes the choice, and with it the mistake.

Submitting a plural translation

keys.submitTranslation needs no prefix: the key is identified in the URL, so its form is already known and an object value can only mean plural classes. The @-prefixed form is accepted too and the prefix is stripped before sending, so a value read from files.listKeys() round-trips safely:

const keys = await api.files.listKeys({ project, file, lang: 'en' });
const key = keys.find((k) => k.key[0] === 'ITEMS');
// key.value === { '@one': '%d item', '@other': '%d items' }

await api.keys.submitTranslation({
  project,
  key,
  lang: 'fr',
  value: { one: '%d élément', other: '%d éléments' }, // or the '@'-prefixed form
});

What the types check

TranslationValue uses the real CLDR classes, so a typo is a compile error — but only in an object literal:

value: { one: '1', otehr: 'n' }  // ✗ TS2353: 'otehr' does not exist
value: someRecord                // ✓ compiles — Key.value is Record<string, any>

Excess-property checking does not apply to values held in variables, so a value round-tripped from the read API is never inspected by the compiler. That path is safe because the client normalises it at runtime, not because the types verified it.

This is the gap plural() closes on the import side: the compiler cannot tell a plural from a nested key group, because both are well-typed — but a tagged value carries the intent regardless of shape.

Import

import.json(request[, config])

Import JSON object as source keys.

Declaring plural keys requires @-prefixed CLDR classes — see Plural keys. Without the prefix you get nested keys instead, with no error.

See: Localazy API Docs

Arguments	Type
request	`ImportJsonRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<File>`	`File`

import { I18nDeprecate } from '@localazy/api-client';

const json = { en: { headers: { name: 'Name' } } };

const file = await api.import.json({
  project: 'project-id', // or Project object
  json,
  i18nOptions: {
    importAsNew: false,
    forceCurrent: false,
    forceSource: false,
    filterSource: true,
    deprecate: I18nDeprecate.NONE,
  },
  fileOptions: {
    name: 'translations.json',
    path: 'path/to/dir',
    module: 'i18n',
    buildType: '',
    productFlavors: [],
  },
});

Export

export.json(request[, config])

Export translated keys as JSON object.

Arguments	Type
request	`ExportJsonRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<I18nJson>`	`I18nJson`

import { Locales } from '@localazy/api-client';

const json = await api.export.json({
  project: 'project-id', // or Project object
  file: 'file-id', // or File object
  langs: [Locales.ENGLISH],
});

Formats

formats.list([config])

List all formats and related options.

See: Localazy API Docs

Arguments	Type
config `optional`	`RequestConfig`

Returns	Type
`Promise<Format[]>`	`Format`

const formats = await api.formats.list();

Screenshots

screenshots.list(request[, config])

List all screenshots in the project.

See: Localazy API Docs

Arguments	Type
request	`ScreenshotsListRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<Screenshot[]>`	`Screenshot`

const screenshots = await api.screenshots.list({
  project: 'project-id', // or Project object
});

screenshots.listTags(request[, config])

List all screenshots tags in the project.

See: Localazy API Docs

Arguments	Type
request	`ScreenshotsListTagsRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<ScreenshotTag[]>`	`ScreenshotTag`

const tags = await api.screenshots.listTags({
  project: 'project-id', // or Project object
});

screenshots.create(request[, config])

Create screenshot.

See: Localazy API Docs

Arguments	Type
request	`ScreenshotCreateRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<string>`	Screenshot id.

const id = await api.screenshots.create({
  project: 'project-id', // or Project object
  encodedData: 'data:image/jpg;base64,...',
});

screenshots.updateImageData(request[, config])

Update the image data of screenshot.

See: Localazy API Docs

Arguments	Type
request	`ScreenshotUpdateImageDataRequest`
config `optional`	`RequestConfig`

Returns
`Promise<void>`

await api.screenshots.updateImageData({
  project: 'project-id', // or Project object
  encodedData: 'data:image/jpg;base64,...',
});

screenshots.update(request[, config])

Update screenshot. Image data are updated with screenshots.updateImageData.

See: Localazy API Docs

Arguments	Type
request	`ScreenshotUpdateRequest`
config `optional`	`RequestConfig`

Returns
`Promise<void>`

await api.screenshots.update({
  project: 'project-id', // or Project object
  screenshot: 'screenshot-id', // or Screenshot object
  comment: 'Customers list.',
  tags: ['customers'],
});

screenshots.delete(request[, config])

Delete screenshot.

See: Localazy API Docs

Arguments	Type
request	`ScreenshotDeleteRequest`
config `optional`	`RequestConfig`

Returns
`Promise<void>`

await api.screenshots.delete({
  project: 'project-id', // or Project object
  screenshot: 'screenshot-id', // or Screenshot object
});

Glossary

glossary.list(request[, config])

List all glossary records in the project.

See: Localazy API Docs

Arguments	Type
request	`GlossaryListRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<GlossaryRecord[]>`	`GlossaryRecord`

const glossaryRecords = await api.glossary.list({
  project: 'project-id', // or Project object
});

glossary.find(request[, config])

Find glossary record specified by id.

See: Localazy API Docs

Arguments	Type
request	`GlossaryFindRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<GlossaryRecord>`	`GlossaryRecord`

const glossaryRecord = await api.glossary.find({
  project: 'project-id', // or Project object
  glossaryRecord: 'glossary-record-id', // or GlossaryRecord object
});

glossary.create(request[, config])

Create glossary record.

See: Localazy API Docs

Arguments	Type
request	`GlossaryCreateRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<string>`	GlossaryRecord id.

import { Locales } from '@localazy/api-client';

const id = await api.glossary.create({
  project: 'project-id', // or Project object
  description: 'Term description',
  caseSensitive: true,
  translateTerm: true,
  term: [{ lang: Locales.ENGLISH, term: 'befitting' }],
});

glossary.update(request[, config])

Update glossary record specified by id.

See: Localazy API Docs

Arguments	Type
request	`GlossaryUpdateRequest`
config `optional`	`RequestConfig`

Returns
`Promise<void>`

import { Locales } from '@localazy/api-client';

await api.glossary.update({
  project: 'project-id', // or Project object
  glossaryRecord: 'glossary-record-id', // or GlossaryRecord object
  description: 'Term description',
  caseSensitive: true,
  translateTerm: true,
  term: [{ lang: Locales.ENGLISH, term: 'befitting' }],
});

glossary.delete(request[, config])

Delete glossary record specified by id.

See: Localazy API Docs

Arguments	Type
request	`GlossaryDeleteRequest`
config `optional`	`RequestConfig`

Returns
`Promise<void>`

await api.glossary.delete({
  project: 'project-id', // or Project object
  glossaryRecord: 'glossary-record-id', // or GlossaryRecord object
});

Webhooks

webhooks.list(request[, config])

List all webhooks in the project.

See: Localazy API Docs

Arguments	Type
request	`WebhooksListRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<Webhook[]>`	`Webhook`

const webhooks = await api.webhooks.list({
  project: 'project-id', // or Project object
});

webhooks.update(request[, config])

Update all webhooks in the project.

See: Localazy API Docs

Arguments	Type
request	`WebhooksUpdateRequest`
config `optional`	`RequestConfig`

Returns
`Promise<void>`

await api.webhooks.update({
  project: 'project-id', // or Project object
  data: [
    {
      enabled: true,
      customId: '1',
      description: 'This is a test webhook',
      url: 'https://example.com/webhook',
      events: [
        'comment_added',
        'import_finished',
        'import_finished_empty',
        'project_published',
        'tag_promoted',
      ],
    },
  ],
});

webhooks.getSecret(request[, config])

Get secret for webhooks in the project. Localazy signs the webhook events it sends to your endpoints and adds a signature in the request header https://localazy.com/docs/api/webhooks-api#security.

See: Localazy API Docs

Arguments	Type
request	`WebhooksGetSecretRequest`
config `optional`	`RequestConfig`

Returns	Type
`Promise<WebhooksSecret>`	`WebhooksSecret`

const secret = await api.webhooks.getSecret({
  project: 'project-id', // or Project object
});

Uh oh!

FilesExpand file tree

api-client-reference.md

Latest commit

History

api-client-reference.md

File metadata and controls

API Client Reference

Table of Contents

Setup

AI Translation

ai.translate(request[, config])

Projects

projects.list(request[, config])

projects.first(request[, config])

Files

files.list(request[, config])

files.first(request[, config])

files.listKeys(request[, config])

files.listKeysPage(request[, config])

files.getContents(request[, config])

Keys

keys.update(request[, config])

keys.delete(request[, config])

keys.deprecate(request[, config])

keys.submitTranslation(request[, config])

keys.setTags(request[, config])

keys.setPriority(request[, config])

Suggestions

suggestions.tm(request[, config])

suggestions.mt(request[, config])

suggestions.ai(request[, config])

Plural keys

plural() — spell it once

The @ prefix is a disambiguator, not decoration

Submitting a plural translation

What the types check

Import

import.json(request[, config])

Export

export.json(request[, config])

Formats

formats.list([config])

Screenshots

screenshots.list(request[, config])

screenshots.listTags(request[, config])

screenshots.create(request[, config])

screenshots.updateImageData(request[, config])

screenshots.update(request[, config])

screenshots.delete(request[, config])

Glossary

glossary.list(request[, config])

glossary.find(request[, config])

glossary.create(request[, config])

glossary.update(request[, config])

glossary.delete(request[, config])

Webhooks

webhooks.list(request[, config])

webhooks.update(request[, config])

webhooks.getSecret(request[, config])

`plural()` — spell it once

The `@` prefix is a disambiguator, not decoration