# LingoHub Developers: all guides and recipes # Introduction What you can build with LingoHub's APIs and which one to use. LingoHub manages the translations of your apps, websites and documents. Its APIs let you automate the work around them: send new source texts in, get finished translations out, and keep LingoHub in step with your code, your content and your release process. ## Which API should I use? New integrations should use API V2. | API | Use it for | Status | Base URL | | --- | --- | --- | --- | | [API V2](/docs/api-v2-overview.md) | All new integrations: workspaces, projects, files, texts, glossaries, automation and integrations | Beta: endpoints and fields can still change | `https://api.lingohub.com/v2` | | [API V1](/docs/api-v1-overview.md) | Existing integrations: projects, resource files, exports, repository pushes and context images | Stable, remains supported | `https://api.lingohub.com/v1` | | [CDN API](/reference/cdn.md) | Loading translations into a running app | Stable | `https://cdn.lingohub.com/v1/distributions` | The three APIs also differ in how you address things and what an error looks like: - **API V2** authenticates with an API key, identifies objects by public IDs such as `pr_019f9d57-…`, and answers errors as RFC 9457 problem details with a `code`. - **API V1** authenticates with an API key, addresses workspaces and projects by the slugs in their URLs (`workspaceUrl`, `projectUrl`), and answers errors with an HTTP status code and a JSON body. - **The CDN API** authenticates with a CDN key that belongs to one project, and takes the environment and type of the distribution in the request body. The [LingoHub CLI](/docs/cli.md) (`lingohub`) calls API V2 from your terminal, scripts and AI agents. It's updated together with API V2, so use it where possible. ## Next steps - [Concepts](/docs/concepts.md): workspaces, stacks, projects, files, keys, segments and texts - [Create an API key](/docs/api-keys.md) - [Install the LingoHub CLI](/docs/cli.md) - [Use LingoHub with AI agents](/docs/ai-agents.md) - [Recipes](/recipes.md): step-by-step examples for common tasks - [Supported file formats](/docs/file-types.md) --- # Concepts The objects the APIs work with, and how they fit together. The guides and the API reference use these words throughout. Read this page once and the endpoints explain themselves. ## The structure ```text Workspace └── Stack languages, members and segments that its projects share ├── Segment a source text and its translations │ └── Text one language of a segment, with its status └── Project files of one format, for example Android XML └── Branch a version of the project's files └── File a resource file └── Key where a segment appears in this file ``` | Object | What it is | | --- | --- | | **Workspace** | Your company's account: its members, plan and stacks. An API key belongs to exactly one workspace. | | **Stack** | Holds the languages, members and segments that one or more projects share. A `PRIVATE` stack belongs to one project; a `PUBLIC` stack can serve several, so the same text is translated once. | | **Project** | A set of files of one project type, such as Android XML, iOS strings or JSON. | | **Branch** | A version of a project's files. Every project has one default branch. Files and keys belong to a branch. | | **File** | A resource file of a branch, for example `values/strings.xml`. The API calls it a *resource*. | | **Key** | The identifier of a segment in one file, for example `login.title`. It is what LingoHub writes into your files. | | **Segment** | One source text and its translations. A segment belongs to the stack, so several keys, in different files, branches and projects, can show the same segment. | | **Text** | One language of a segment, with its status. The text of the source language is the *source text*; the others are *translations*. | | **Variant** | The content of a text for one plural form and one device. Most texts have a single variant. | ## A segment is not a key This is the distinction that matters most when you change content through the API: - What belongs to the **segment** is shared: its texts, their statuses, its description and labels. Change a translation and every key that uses the segment shows the new text, in every project of the stack. - What belongs to the **key** is local to one file: its name and its position in the file. Before you edit a segment, check which keys use it. The recipe [Update a translation safely](/recipes/update-a-translation-safely-api-v2.md) shows the full flow. ## Languages A stack has exactly one *source language*; its other languages are *target languages*. A project uses the languages of its stack. Language codes look like `en`, `de` or `pt-BR`. ## More objects | Object | What it is | | --- | --- | | **Import** and **export** | Asynchronous jobs that read files into a branch or write them out. See [Imports and exports](/docs/api-v2-imports-and-exports.md). | | **Label** | A tag on segments, to categorize and filter content. | | **Context image** | A screenshot that shows translators and LINAs where a text appears. | | **Glossary** and **term** | The terminology LINA uses for translation and that the terminology check enforces. | | **Style guide** | Tone, audience and language rules that guide AI translation. | | **LINA** | LingoHub's AI translation agent. A LINA translates and reviews texts with the engines, glossaries and style guides you give it. | | **Distribution** and **release** | A distribution delivers a project's translations to running apps over the CDN; a release is one published version of them. | | **Webhook endpoint** | A URL of yours that receives LingoHub events. See [Webhooks](/docs/api-v2-webhooks.md). | ## Identifiers API V2 identifies every object by a public ID: a prefix that names the type, followed by a UUID. | Prefix | Object | Prefix | Object | | --- | --- | --- | --- | | `stack_` | Stack | `seg_` | Segment | | `pr_` | Project | `la_` | Label | | `prb_` | Branch | `ci_` | Context image | | `rc_` | File (resource) | `gls_` | Glossary | | `rin_` | Import | `te_` | Term | | `whe_` | Webhook endpoint | `sg_` | Style guide | Take IDs from API responses; never build them yourself. API V1 does not use public IDs: it addresses workspaces and projects by the slugs in their URLs. See the [API V1 overview](/docs/api-v1-overview.md). --- # API keys Create a key, choose its permissions and send it with every request. API V1 and API V2 use the same API keys. The CDN API uses separate CDN keys, which belong to a project. See the [CDN API reference](/reference/cdn/operations/tags/distributions.md). ## Create a key Follow [How to create an API key](https://help.lingohub.com/en/articles/6775959-how-to-create-an-api-key) in the Help Center. When you create a key, you can: - set an expiration date (optional); - choose its [permissions](https://help.lingohub.com/en/articles/13941129-what-are-roles-and-permissions). Permissions are set per workspace and per stack: workspace permissions cover workspace-wide areas such as members and API access, and stack permissions cover the projects, files, languages and texts of a stack. Copy the key right away: LingoHub shows it only once. New keys start with `lh-api_`. Older keys that start with `lingo_` keep working. To use the [LingoHub CLI](/docs/cli.md), run `lingohub login` instead: after you confirm in LingoHub, it creates a self-managed API key for you and stores it on your computer. A self-managed key acts with your own current permissions, in one workspace, with two limits: it can view billing and the subscription at most, and it cannot manage workspaces. These limits also apply to the workspace owner. ## Send the key Pass the key as a Bearer token in the `Authorization` header: ```shell curl https://api.lingohub.com/v2/api-key \ -H "Authorization: Bearer $LINGOHUB_API_KEY" ``` [`GET /v2/api-key`](/reference/v2/operations/getapikey.md) returns the key's own scope and effective permissions, so it's a quick way to check a new key. The same header works for API V1: ```shell curl https://api.lingohub.com/v1/projects \ -H "Authorization: Bearer $LINGOHUB_API_KEY" ``` ## Keep keys safe - Store keys in a secret manager or CI secret, never in source code. - Give each integration its own key, with only the permissions it needs. - Delete a key in the workspace settings as soon as it's no longer needed or may have leaked. --- # LingoHub CLI Install the lingohub command, sign in through the browser and use API V2 from your terminal, scripts and AI agents. `lingohub` is the command-line client for [API V2 (Beta)](/docs/api-v2-overview.md). It signs you in through the browser, works with your workspace, stacks and projects, runs imports and exports, and serves the API to AI agents over MCP. It's open source: [lingohub/lingohub-cli](https://github.com/lingohub/lingohub-cli). The CLI is updated together with API V2. While V2 is in beta, keep the CLI up to date to stay compatible. ## Install macOS and Linux with [Homebrew](https://brew.sh): ```shell brew install lingohub/cli/lingohub ``` macOS and Linux without Homebrew: ```shell curl --proto '=https' --tlsv1.2 -LsSf https://github.com/lingohub/lingohub-cli/releases/latest/download/lingohub-installer.sh | sh ``` Windows (PowerShell): ```powershell powershell -ExecutionPolicy Bypass -c "irm https://github.com/lingohub/lingohub-cli/releases/latest/download/lingohub-installer.ps1 | iex" ``` Archives for macOS (Apple silicon and Intel), Linux (x86_64 and ARM64) and Windows (x86_64), with checksums, are on the [releases page](https://github.com/lingohub/lingohub-cli/releases). ## Sign in ```shell lingohub login ``` `lingohub login` opens a confirmation page in LingoHub and prints its link with a verification code. Check that the page shows the same code, pick the workspace and confirm. The CLI then stores a new self-managed API key in `~/.lingohub`, readable only by you. The key acts with your own permissions, is named after your computer and is valid for 90 days; run `lingohub login` again for a new one. Your workspace must allow self-managed API keys. An admin turns them on with **Allow self-managed API keys** in the workspace's security settings. `lingohub logout` revokes the stored key and removes it from `~/.lingohub`. In CI, or with a key created in LingoHub, set `LINGOHUB_API_KEY` instead. It takes precedence over the stored key. See [API keys](/docs/api-keys.md). ## First commands ```shell lingohub workspace lingohub project list lingohub api operations lingohub api call getApiKey ``` - Add `--json` to get the API's JSON on stdout, for scripts. - `lingohub api call OPERATION` calls any JSON operation of the [API V2 reference](/reference/v2.md) by its operation ID. - `lingohub COMMAND --help` lists the options of each command. - `lingohub tui` opens an interactive dashboard. ## Import and export files `lingohub api call` sends a JSON operation, `lingohub api upload` sends a file, `lingohub api wait` polls a job until it has finished, and `lingohub api download-export` saves the exported ZIP. ```shell # Find the project's default branch BRANCH_ID=$(lingohub api call getProject --path projectId="$PROJECT_ID" --json | jq -r '.default_branch_id') # Import a file, wait for the import and check its files IMPORT_ID=$(lingohub api upload createImport --path branchId="$BRANCH_ID" \ --upload en.json --form language_code=en \ --idempotency-key "$(uuidgen)" --json | jq -r '.data.id') lingohub api wait getImport --path importId="$IMPORT_ID" --json lingohub api call listImportEntries --path importId="$IMPORT_ID" --query limit=100 --json # Export two languages, wait for the export and download the ZIP EXPORT_ID=$(lingohub api call createExport --path branchId="$BRANCH_ID" \ --field 'language_codes=["de","fr"]' \ --idempotency-key "$(uuidgen)" --json | jq -r '.data.id') lingohub api wait getExport --path exportId="$EXPORT_ID" --json lingohub api download-export "$EXPORT_ID" --output translations.zip ``` `lingohub api wait` reads the job every 2 seconds for up to 300 seconds; change that with `--interval` and `--timeout`. It exits with an error when the job ends in any status other than `SUCCEEDED`, so check the entries before you retry. `lingohub api download-export` never overwrites an existing file. Parameters: `--path NAME=VALUE` sets a path parameter and `--query NAME=VALUE` a query parameter. `--field NAME=JSON` sets one field of the JSON body; the value is JSON, so a string needs its quotes, as in `--field 'name="My App"'`. `lingohub api upload` takes the file with `--upload FILE` and its other form fields with `--form NAME=VALUE`. `--idempotency-key VALUE` and `--if-match '"ETAG"'` send the `Idempotency-Key` and `If-Match` headers; see [Safe retries and conditional updates](/docs/api-v2-safe-retries.md). `--include-headers` prints the HTTP status and response headers such as `ETag` and `Location` on stderr, and `--json` prints the response JSON on stdout. The [Workflow and recovery guide](/docs/api-v2-workflow-guide.md) describes the complete file workflow. ## AI agents `lingohub api mcp-serve` serves API V2 to MCP clients over stdio. It uses the same key as the CLI. By default it offers a small set of read-only tools; select operations or tags, or use `--all`, to offer more, including changes. ```json {"mcpServers": {"lingohub": {"command": "lingohub", "args": ["api", "mcp-serve"]}}} ``` [Use LingoHub with AI agents](/docs/ai-agents.md) has more on this. ## Upgrade ```shell brew upgrade lingohub # installed with Homebrew lingohub upgrade # installed with an installer ``` Interactive commands mention a newer release at most once a day. More examples are in the [README](https://github.com/lingohub/lingohub-cli#readme) and the [workflow cookbook](https://github.com/lingohub/lingohub-cli/blob/main/docs/cookbook.md). --- # Use LingoHub with AI agents Three ways to give an AI agent access to LingoHub, and the rules it should follow. An AI agent can work with LingoHub in three ways. Start with the first one that fits your setup. | Way | Use it when | What the agent gets | | --- | --- | --- | | [MCP tools](#mcp-tools) | Your agent supports MCP, such as Claude Code, Cursor or VS Code | API V2 operations as tools, read-only by default | | [The CLI](#the-cli) | Your agent can run shell commands | Every API V2 operation as a command with JSON output | | [The API and these docs](#the-api-and-these-docs) | The agent writes an integration for you | The OpenAPI specs and every page of this site as Markdown | All three use an API key. Read [Keys and permissions](#keys-and-permissions) before you give an agent one. ## MCP tools The [LingoHub CLI](/docs/cli.md) serves API V2 to MCP clients. Install the CLI, run `lingohub login`, then register the server with your client: ```json { "mcpServers": { "lingohub": { "command": "lingohub", "args": ["api", "mcp-serve"] } } } ``` In Claude Code, one command does the same: ```shell claude mcp add lingohub -- lingohub api mcp-serve ``` By default the server offers a small set of read-only tools, so an agent can look around but not change anything. Offer more deliberately: ```shell lingohub api mcp-serve --tag Projects --tag Imports # every operation of these groups lingohub api mcp-serve --operation createImport # single operations lingohub api mcp-serve --all # everything, including changes ``` `lingohub api mcp-tools` lists the tools a selection would offer, without starting a server. The tool names are the operation IDs of the [API V2 reference](/reference/v2.md). ## The CLI An agent that can run commands needs no MCP setup. These commands are enough to start: ```shell lingohub --json api call getApiKey # which key am I, and what may it do? lingohub --json api call getWorkspace lingohub api operations # every operation the CLI knows, offline ``` `lingohub api call OPERATION` calls any JSON operation by its operation ID; `--json` puts the API's JSON on stdout. The [CLI page](/docs/cli.md) shows how to pass parameters and how to import and export files. The CLI is updated together with API V2, so an agent that uses it keeps working when the API changes during the beta. ## The API and these docs An agent that writes code against the API needs the contract and the guides in a form it can read: - **OpenAPI specs.** [API V2](https://api.lingohub.com/public/api-docs/v2), [API V1](https://api.lingohub.com/public/api-docs/v1) and the [CDN API](https://api.lingohub.com/public/api-docs/CDN), as JSON. - **An index.** [`/llms.txt`](/llms.txt) lists every guide and recipe with a one-line description, and links an index of each API's operations. - **Every page as Markdown.** Append `.md` to the URL of any page of this site, or request the page with `Accept: text/markdown`. The page menu **Copy page** copies the same Markdown. - **Everything in one file.** [`/llms-full.txt`](/llms-full.txt) holds all guides and recipes. - **The workflow guide.** The [Workflow and recovery guide](/docs/api-v2-workflow-guide.md) is the compact version of the API V2 rules, written for agents. Every API build also serves it, next to its own spec. ## Rules to give your agent `/llms.txt` starts with these rules. Put them into your agent's instructions when it does not read that file itself: - Use API V2. It is in beta: check the deployed spec instead of relying on memory. - Take IDs from API responses. Never construct one. - Page through lists with `cursor` until `has_more` is false, with the same `filter` on every page. - Send an `Idempotency-Key` with every `POST` and retry with the same key. After an uncertain result, look at the resource before you send the request again. - Change existing objects with `If-Match`. On `412`, read again and decide again; never overwrite blindly. - An accepted import or export is not a finished one. Poll the job and read its entries. - A segment is shared by every key that shows it. Check where it is used before you change it. - Never print or commit an API key. ## Keys and permissions An agent acts with the permissions of its key, so give it a key of its own with only what the task needs: - For work on your own computer, `lingohub login` stores a personal key that follows your permissions and expires after 90 days. - For an agent that runs unattended, create a key in the workspace settings, limit it to the stacks and permissions it needs, and set it as `LINGOHUB_API_KEY`. See [API keys](/docs/api-keys.md). - Start read-only. The MCP server's default tools change nothing; add operations that write when the agent needs them. - LingoHub keeps a log of each key's API V2 requests for a retention period: the [API logs](/reference/v2/operations/tags/api-logs.md) show what an agent called. --- # API V2 (Beta) overview Programmatic access to workspaces, projects, files, texts, glossaries and automation. > **Beta** > > API V2 is in beta. Endpoints, request and response fields, and behavior can still change. If you call the HTTP API directly, be prepared to update your integration when V2 changes. > > The [LingoHub CLI](/docs/cli.md) is updated together with the API. Use it where possible to stay compatible as V2 changes. [Concepts](/docs/concepts.md) explains the objects the API works with: workspaces, stacks, projects, branches, files, keys, segments and texts. ## What you can do - Manage workspace members and invitations, stacks, projects, branches and languages. - Import and export resource files as asynchronous jobs, and see what each import changed. - Read and edit keys, segments and texts, labels and context images. - Manage glossaries, terms and style guides. - Configure LINAs and run them, set up webhooks, and connect Git repositories and CMS integrations. - Create backups and restore them, read distributions and their releases, and list and update API keys. - Read API logs and audit logs. ## Base URL The base URL is `https://api.lingohub.com/v2`. The paths in the reference include the `/v2` prefix: `GET /v2/workspace` is `https://api.lingohub.com/v2/workspace`. ## Authentication Send an API key as a Bearer token: `Authorization: Bearer lh-api_…`. API V2 accepts API keys only; browser sessions don't work. See [API keys](/docs/api-keys.md). ## First request ```shell curl https://api.lingohub.com/v2/workspace \ -H "Authorization: Bearer $LINGOHUB_API_KEY" ``` ## Conventions - **JSON** with `snake_case` field names. Every object has an `object_type`. - **IDs** are public IDs: a type prefix plus a UUID, for example `pr_019f9d57-d0ec-7fa2-…`. Use the IDs from responses. API V1 URL slugs aren't accepted. - **Timestamps** are ISO 8601 in UTC, for example `created_at` and `updated_at`. - **Strict input:** unknown fields, unknown query parameters and duplicate JSON keys are rejected, not ignored. - **Updates** use `PATCH` with JSON merge-patch: omitted fields stay unchanged, and `null` clears a field that allows it. `PUT` replaces a complete sub-resource, such as a project's backup settings. - **Lists** use cursor pagination and a `filter` parameter. See [Pagination and filtering](/docs/api-v2-pagination-and-filtering.md). - **Long-running work** such as imports, exports, project moves and backup restores returns a job. Poll it until it reaches a final status. See [Imports and exports](/docs/api-v2-imports-and-exports.md). - **Safe retries:** send an `Idempotency-Key` with `POST` requests, and `If-Match` with the ETag you read for conditional updates. See [Safe retries and conditional updates](/docs/api-v2-safe-retries.md). ## Errors Errors follow RFC 9457 Problem Details, with a machine-readable `code`, a `request_id` to quote to support, and field-level `errors`. See [Errors and rate limits](/docs/api-v2-errors-and-rate-limits.md). ## Rate limits Requests are limited per API key and per workspace. Over the limit, the API answers `429 rate_limit_exceeded` with a `Retry-After` header. The `RateLimit` and `RateLimit-Policy` headers help you pace requests before that happens. ## Guides and recipes - [Pagination and filtering](/docs/api-v2-pagination-and-filtering.md), [Errors and rate limits](/docs/api-v2-errors-and-rate-limits.md), [Safe retries and conditional updates](/docs/api-v2-safe-retries.md), [Imports and exports](/docs/api-v2-imports-and-exports.md) and [Webhooks](/docs/api-v2-webhooks.md). - Step-by-step [recipes](/recipes.md) with Shell and Python code: [Import a file](/recipes/import-a-file-api-v2.md), [Export translations](/recipes/export-translations-api-v2.md), [Update a translation safely](/recipes/update-a-translation-safely-api-v2.md) and [List with filters and cursors](/recipes/list-with-filters-and-cursors-api-v2.md). ## Machine-readable docs - [OpenAPI spec of API V2](https://api.lingohub.com/public/api-docs/v2). - [Reference files on the API host](https://api.lingohub.com/public/api-v2/): the workflow guide, one page per operation group and an `llms.txt` index for AI agents. - [`llms.txt`](/llms.txt) of this site. - [Workflow and recovery guide](/docs/api-v2-workflow-guide.md): the API host's workflow guide as a page of this site. - [Use LingoHub with AI agents](/docs/ai-agents.md). --- # Pagination and filtering Page through lists with cursors and select items with filters. ## Pagination List endpoints use cursor pagination with the `cursor` and `limit` query parameters. `limit` defaults to 20, with a maximum of 100. Each response contains: - `data`: the items of this page; - `has_more`: whether more items follow; - `next_cursor`: an opaque token for the next page, `null` on the last page. To read a whole collection, repeat the request with `cursor` set to the previous response's `next_cursor` until `has_more` is `false`: ```shell curl "https://api.lingohub.com/v2/projects?limit=100" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" curl "https://api.lingohub.com/v2/projects?limit=100&cursor=$NEXT_CURSOR" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" ``` Keep every other query parameter the same while you follow a cursor. A cursor belongs to the collection, the filter and the sort order it was created with. If you change any of them, the request fails with `400 invalid_cursor`. Lists don't return a total count. Items created or deleted before the cursor position aren't revisited during an iteration. > **Lists of a connected provider** > > The lists that read from a connected provider, such as Git repositories and branches or Contentful spaces, take no `filter`. Some of them return the provider's complete list and take no `cursor` or `limit`. Each operation in the [API reference](/reference/v2.md) documents its parameters. ## Filtering Lists accept a `filter` query parameter: URL-encoded JSON that selects items (`where`) and orders them (`sort`). - `where` holds exactly one `_and` or `_or` with an array of clauses. - A clause is either a nested `_and`/`_or`, or one field with exactly one operator. - Fields are named `[]` after the list's items, for example `project[name]`, and compare the values the responses show. - `sort` lists fields in order, each prefixed with `+` (ascending) or `-` (descending). Each list documents its fields, their operators and values, and which fields can sort, in its `filter` parameter and its filter schema (for example `ProjectFilter`) in the API reference. ### Example Projects whose name contains "app" and that are either of type `STANDARD_JSON` or created this year, newest first: ```json { "where": { "_and": [ { "project[name]": { "_icontains": "app" } }, { "_or": [ { "project[type]": { "_eq": "STANDARD_JSON" } }, { "project[created_at]": { "_gte": "2026-01-01T00:00:00Z" } } ] } ] }, "sort": ["-project[created_at]"] } ``` With curl, let it URL-encode the filter for you: ```shell curl -G "https://api.lingohub.com/v2/projects" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" \ --data-urlencode 'filter={"where":{"_and":[{"project[name]":{"_icontains":"app"}}]},"sort":["-project[created_at]"]}' ``` ### Invalid filters A field, operator or value the list doesn't support returns `400 invalid_filter`. The error points to the exact place in the filter and names what is supported there: ```json { "status": 400, "code": "invalid_filter", "errors": [ { "parameter": "filter", "pointer": "#/where/_and/1/_or/0/project[type]/_eq", "code": "enum", "detail": "'JSON' is not a value of 'project[type]'. Values: ANDROID_XML, IOS_STRINGS, ..." } ] } ``` --- # Errors and rate limits The error format, the error code catalog and the rate limit headers. ## Error format All errors follow [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details, returned as `application/problem+json`: ```json { "type": "https://api.lingohub.com/errors/validation-failed", "title": "Validation failed", "status": 422, "detail": "One or more fields failed validation.", "instance": "/v2/projects", "code": "validation_failed", "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "errors": [ { "pointer": "#/name", "parameter": null, "code": "minLength", "detail": "must be at least 2 characters long" } ] } ``` | Field | Meaning | | :--- | :--- | | `code` | Machine-readable error code. Use it, not `title` or `detail`, in your error handling. | | `type` | Link to a page that explains the error. | | `title` | Short, constant summary of the error. | | `status` | HTTP status code. | | `detail` | Human-readable explanation of this occurrence. | | `instance` | Path of the request that failed. | | `request_id` | Correlation ID, also in the `X-Request-ID` header. Quote it when you contact support. | | `errors` | Rejected fields or parameters, when the problem concerns specific input. `pointer` locates a body field (JSON Pointer), `parameter` a query, path or header parameter or a multipart field. | | `required_permission` | On `403`, the permission the API key is missing. | A resource your key isn't allowed to see can return `404 resource_not_found`, the same as one that doesn't exist. ## Error codes | Code | HTTP status | Meaning | |---|---|---| | `invalid_json` | 400 | Invalid JSON | | `invalid_parameter` | 400 | Invalid parameter | | `missing_parameter` | 400 | Missing parameter | | `unknown_parameter` | 400 | Unknown parameter | | `invalid_filter` | 400 | Invalid filter | | `invalid_cursor` | 400 | Invalid cursor | | `bad_request` | 400 | Bad request | | `missing_api_key` | 401 | Missing API key | | `invalid_api_key` | 401 | Invalid API key | | `expired_api_key` | 401 | Expired API key | | `revoked_api_key` | 401 | Revoked API key | | `disabled_api_key` | 401 | Disabled API key | | `insufficient_permissions` | 403 | Insufficient permissions | | `resource_not_found` | 404 | Resource not found | | `route_not_found` | 404 | Route not found | | `method_not_allowed` | 405 | Method not allowed | | `not_acceptable` | 406 | Not acceptable | | `precondition_failed` | 412 | Precondition failed | | `content_too_large` | 413 | Content too large | | `unsupported_media_type` | 415 | Unsupported media type | | `already_exists` | 409 | Already exists | | `idempotency_outcome_unknown` | 409 | Idempotency outcome unknown | | `idempotency_key_in_use` | 409 | Idempotency key in use | | `stack_not_empty` | 409 | Stack not empty | | `branch_not_ready` | 409 | Branch not ready | | `backup_not_ready` | 409 | Backup not ready | | `backup_in_use` | 409 | Backup in use | | `default_branch_protected` | 409 | Default branch protected | | `owner_membership_protected` | 409 | Owner membership protected | | `source_language_protected` | 409 | Source language protected | | `branch_limit_reached` | 409 | Branch limit reached | | `context_image_limit_reached` | 409 | Context image limit reached | | `automation_limit_reached` | 409 | Automation limit reached | | `translation_order_pending` | 409 | Translation order pending | | `git_integration_not_configured` | 409 | Git integration not configured | | `branch_git_integration_not_configured` | 409 | Branch git integration not configured | | `git_integration_unauthorized` | 409 | Git integration unauthorized | | `conflict` | 409 | Conflict | | `validation_failed` | 422 | Validation failed | | `idempotency_key_mismatch` | 422 | Idempotency key mismatch | | `rate_limit_exceeded` | 429 | Rate limit exceeded | | `internal_error` | 500 | Internal error | | `upstream_error` | 502 | Upstream error | | `service_unavailable` | 503 | Service unavailable | | `upstream_timeout` | 504 | Upstream timeout | ## Rate limits Requests are limited per API key and per workspace, where the workspace limit counts all of its keys together. When you exceed either limit, the API answers `429 rate_limit_exceeded` with a `Retry-After` header that gives the seconds to wait. By default, the limits are 180 requests per 60 seconds for an API key and 600 requests per 60 seconds for a workspace. These are defaults: the `RateLimit-Policy` header reports the limits that apply to your request. Responses to authenticated requests also carry the `RateLimit` and `RateLimit-Policy` headers ([IETF draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/)): - `RateLimit-Policy` lists the policies that apply, each with its request quota `q` per window of `w` seconds. For example: `"api-key";q=180;w=60, "workspace";q=600;w=60`. - `RateLimit` reports the policy closest to rejection: the requests remaining right now (`r`) and the seconds until the full quota is available again (`t`). For example: `"api-key";r=42;t=7`. Use these headers to pace your requests instead of waiting for a `429`. They are advisory: they're missing when a request fails authentication or the limiter state is briefly unknown. A `429` never makes it safe to repeat a write whose outcome you don't know. See [Safe retries and conditional updates](/docs/api-v2-safe-retries.md). --- # Safe retries and conditional updates Retry writes with idempotency keys and update safely with ETags. Network errors and timeouts can leave you unsure whether a write went through. API V2 gives you two tools to handle that safely. ## Idempotency keys for POST requests Send a unique `Idempotency-Key` header with each intended `POST` operation, and send the same key again if you retry that operation: ```shell curl -X POST "https://api.lingohub.com/v2/branches/$BRANCH_ID/exports" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"language_codes": ["de", "fr"]}' ``` - If the first request succeeded, a retry with the same key returns the original response with `Idempotent-Replayed: true` instead of running the operation again. Successful responses are kept for 24 hours by default. - If the first request is still running, you get `409 idempotency_key_in_use` with a `Retry-After` header. - If the outcome of the first request is unknown, you get `409 idempotency_outcome_unknown`. Check the affected resource before you start a new operation with a new key. - Reusing a key with a different request returns `422 idempotency_key_mismatch`. - A `4xx` rejection releases the key, so you can fix the request and retry with the same key. - A key must have 1 to 255 characters. - A response that contains a secret is never replayed. This applies to creating a webhook endpoint and to rotating its signing secret: a retry with the same key gets `409 idempotency_outcome_unknown` and doesn't run the operation again. If you lost the response, rotate the secret. This protection is best effort, not exactly-once execution. Never blindly retry an uncertain write with a new key: look at the resource first. ## Conditional updates with ETags Many resources return an `ETag` header. Send it back in `If-Match` to make sure you only change what you last read: ```shell # 1. Read the segment and note its ETag curl -i "https://api.lingohub.com/v2/segments/$SEGMENT_ID" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" # 2. Update it only if nobody changed it in the meantime curl -X PATCH "https://api.lingohub.com/v2/segments/$SEGMENT_ID" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" \ -H "If-Match: $SEGMENT_ETAG" \ -H "Content-Type: application/merge-patch+json" \ -d '{"description": "Label on the sign-in button"}' ``` - Send the complete quoted ETag. Weak ETags never match. - `If-Match` is optional: without it, the write is unconditional. - Every `PATCH`, `PUT` and `DELETE` operation accepts `If-Match`, and so do the `POST` actions that document it, such as [changing the status of a text](/reference/v2/operations/transitionsegment.md). For an action, send the ETag of the resource itself. - Any other operation rejects the header with `400 invalid_parameter`. - `412 precondition_failed` means the resource changed since you read it. Read it again and decide whether your change still applies; don't overwrite it automatically. - `PUT` responses don't include an ETag. Read the resource again to get the current one. - A replayed response carries the original ETag, which can be out of date by then. - ETags are for write preconditions. API V2 doesn't use them for conditional `GET` caching. ## Shared content Some edits reach further than one place. A segment holds the text that one or more keys share, so editing a segment's text or description changes it for every key that uses it. Use [`GET /v2/segments/{segmentId}/keys`](/reference/v2/operations/listsegmentkeys.md) to see which keys use a segment before you edit it. --- # Imports and exports Upload files and download translations as asynchronous jobs. Imports and exports run as asynchronous jobs. You start a job and get `202 Accepted` right away, with the job in the response: `{"object_type": "JOB", "job_type": "IMPORT", "data": {...}}`. The job's ID is `data.id`, and the `Location` header holds the URL to poll. Poll the job until it reaches a final status. The same pattern applies to other long-running work, such as project moves and backup restores. Step-by-step versions with Shell and Python code are in the recipes [Import a file](/recipes/import-a-file-api-v2.md) and [Export translations](/recipes/export-translations-api-v2.md). ## Find the branch Files belong to a project branch. The project's `default_branch_id` is the branch most integrations work on: ```shell curl "https://api.lingohub.com/v2/projects/$PROJECT_ID" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" ``` To work on another branch, list them with [`GET /v2/projects/{projectId}/branches`](/reference/v2/operations/listbranches.md). A new branch must finish its setup first: until its `initialization_status` is `SUCCEEDED`, imports and exports fail with `409 branch_not_ready`. ## Import a file Upload the file as `multipart/form-data`. A file whose name ends in `.zip` is imported as an archive of files. ```shell curl -X POST "https://api.lingohub.com/v2/branches/$BRANCH_ID/imports" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" \ -H "Idempotency-Key: $IMPORT_KEY" \ -F "file=@en.json" \ -F "language_code=en" \ -F "path=src/i18n" ``` | Form field | Required | Meaning | | :--- | :--- | :--- | | `file` | Yes | The file or `.zip` archive to import. | | `language_code` | No | Language of the file, or of every file in the archive. Omit it to detect the language from each file's name and path. | | `path` | No | Folder to import into, for example `src/i18n/de`. Omit it to import at the project root. | Each file can have up to 10 MB, or 50 MB in a document project. The whole upload can have up to 100 MB. A file in a language the branch doesn't have yet adds that language as a target language. The API rejects an upload it can't import: - `413 content_too_large`: the upload exceeds the maximum size. - `422 validation_failed`: a form field is invalid. `errors` names the field and the reason. For `file`, the reasons are `file_empty`, `unsupported_file_extension`, `file_too_large`, `invalid_archive`, `empty_archive` and `not_supported`. Then poll the import and read its entries: ```shell curl "https://api.lingohub.com/v2/imports/$IMPORT_ID" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" curl "https://api.lingohub.com/v2/imports/$IMPORT_ID/entries" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" ``` There is one entry per file and language. Files are imported one at a time. After the first file that fails, the remaining entries are `SKIPPED`. `UNCHANGED` means the file hasn't changed since its last import, so the import left it alone. After an import, [`GET /v2/imports/{importId}/changes`](/reference/v2/operations/listimportchanges.md) lists what it changed: one item per segment and file, with the key change and the text changes in each language. ## Export translations Request an export, poll it, then download the ZIP from its `download_url`: ```shell curl -X POST "https://api.lingohub.com/v2/branches/$BRANCH_ID/exports" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" \ -H "Idempotency-Key: $EXPORT_KEY" \ -H "Content-Type: application/json" \ -d '{"language_codes": ["de", "fr"]}' curl "https://api.lingohub.com/v2/exports/$EXPORT_ID" \ -H "Authorization: Bearer $LINGOHUB_API_KEY" ``` The request must have a JSON body. `language_codes` selects the languages; send `{}` to export every language. A language the branch doesn't have is rejected with `422 validation_failed`. Only a `SUCCEEDED` export has a `download_url`. The URL is pre-signed, points to a ZIP with the exported files and is valid for 24 hours, until `download_url_expires_at`. Read the export again to get a fresh link. An export stops at the first file that fails and ends `FAILED`. The files exported before that can still be downloaded: each succeeded entry of [`GET /v2/exports/{exportId}/entries`](/reference/v2/operations/listexportentries.md) has its own `download_url`. ## Job statuses | Status | Meaning | | :--- | :--- | | `QUEUED`, `PROCESSING` | Still running. Poll again later. | | `SUCCEEDED` | Finished: every file was imported or exported. | | `PARTIALLY_SUCCEEDED` | Some of the work failed: an import in which some files were imported before one failed, or a push to Git or a content platform in which some items failed. Look at the entries. | | `FAILED` | An import: nothing was imported. An export: a file failed and the export stopped. `status_details` says why. | | `CANCELLED` | The project was deleted before the job ran. | | `SKIPPED` | An integration found nothing to import or push. | ## Good practice - An accepted job can still fail or only partly succeed. Don't treat `202 Accepted` or a download URL alone as success. - After a partial or failed result, read `status_details`, all pages of the job's entries and its logs (`/logs`) before you retry. - Keep the job IDs you get back, so that a client interruption doesn't force you to submit the work again. - Send an `Idempotency-Key` with each import and export request. See [Safe retries and conditional updates](/docs/api-v2-safe-retries.md). --- # Webhooks Receive LingoHub events at your own endpoint and verify their signatures. Webhooks let LingoHub tell your system when something happens, for example when an import completes or a project is created, instead of you polling the API. LingoHub sends each event as an HTTPS `POST` to an endpoint you register, signed so you can check that it came from LingoHub. LingoHub follows the [Standard Webhooks](https://www.standardwebhooks.com) specification, so you can verify requests with any Standard Webhooks library. ## Create an endpoint Register the URL and the events it should receive. `["*"]` subscribes to every event type, including types added later. ```shell curl -X POST https://api.lingohub.com/v2/webhook-endpoints \ -H "Authorization: Bearer $LINGOHUB_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/hooks/lingohub", "description": "Build pipeline", "event_types": ["import.completed", "import.failed", "export.completed"] }' ``` The response is `201 Created` with the endpoint and its signing secret (`whsec_…`). LingoHub shows the secret **only once**: store it in your secret manager right away. A retry with the same `Idempotency-Key` doesn't return the secret again. If you lost it, rotate the secret. ```json { "object_type": "WEBHOOK_ENDPOINT", "id": "whe_0197c8f2-5a6b-7cde-8f12-3456789abcde", "secret": "whsec_…", "url": "https://example.com/hooks/lingohub", "description": "Build pipeline", "status": "ENABLED", "event_types": ["import.completed", "import.failed", "export.completed"], "stack_id": null, "project_id": null, "api_version": "2026-07-01", "consecutive_failures": 0, "last_success_at": null, "last_failure_at": null, "disabled_at": null, "created_at": "2026-11-04T10:30:00.123Z", "updated_at": "2026-11-04T10:30:00.123Z" } ``` | Field | Required | Meaning | | :--- | :--- | :--- | | `url` | Yes | An `https` URL on port 443 whose host resolves only to public addresses. At most 2,048 characters. | | `event_types` | Yes | The event types to receive, or `["*"]` for all. | | `description` | No | Up to 4,096 characters. | | `stack_id` or `project_id` | No | Limits the endpoint to the events of one stack or one project. You can set one of them, not both. | An endpoint scoped to a stack or project receives only events that belong to it. Workspace-level events, such as `member.*`, `glossary.*`, `label.*`, `api_key.*` and `webhook_endpoint.*`, reach only endpoints without a scope. Managing webhooks needs an API key with the **API access** permission: view to read endpoints and deliveries, manage to change them. ## Events `GET /v2/webhook-event-types` lists every type you can subscribe to, with its category. The main ones: | Category | Event types | | :--- | :--- | | Projects and branches | `project.created`, `project.updated`, `project.deleted`, `branch.created`, `branch.updated`, `branch.set_default`, `branch.deleted` | | Languages | `language.added`, `language.removed`, `language.settings_changed`, `language.completed` | | Resources | `resource.created`, `resource.updated`, `resource.renamed`, `resource.deleted` | | Imports and exports | `import.started`, `import.completed`, `import.failed`, `export.completed`, `export.failed` | | Automation and AI | `pretranslation.completed`, `ai_translation.completed`, `ai_review.completed` | | Quality | `quality_check.finding_created`, `quality_check.finding_resolved` | | Translation orders | `order.created`, `order.quoted`, `order.submitted`, `order.in_progress`, `order.completed`, `order.cancelled` | | Members and stacks | `member.invited`, `member.joined`, `member.declined`, `member.removed`, `member.role_changed`, `stack.created`, `stack.updated`, `stack.deleted` | | Glossaries, style guides and LINAs | `glossary.*`, `term.*`, `style_guide.*`, `translation_memory.updated`, `translation_memory.exported`, `lina.*` | | Project configuration | `label.*`, `backup.created`, `backup.deleted`, `integration.connected`, `integration.updated`, `integration.disconnected`, `linguistic_engine_connection.*`, `linguistic_engine_model.*` | | Platform | `api_key.*`, `webhook_endpoint.*` | An entry such as `glossary.*` is shorthand for all events of that object. In `event_types`, send the exact names that `GET /v2/webhook-event-types` returns, or `["*"]`. Events fire for changes made in the LingoHub app, through the API and by background jobs alike. ## The request ```http POST /hooks/lingohub HTTP/1.1 Content-Type: application/json User-Agent: LingoHub-Webhooks/1 webhook-id: evt_0197c8f2-5a6b-7cde-8f12-3456789abcde webhook-timestamp: 1793783705 webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= {"id":"evt_0197c8f2-5a6b-7cde-8f12-3456789abcde","type":"import.completed","api_version":"2026-07-01","created_at":"2026-11-04T09:15:02.123+00:00","workspace_id":"space_0197c8f2-5a6b-7cde-8f12-3456789abc01","data":{"id":"rin_0197c8f2-5a6b-7cde-8f12-3456789abc02","status":"SUCCEEDED","segments_created":42,"segment_texts_updated":17}} ``` | Header | Meaning | | :--- | :--- | | `webhook-id` | The event ID. It stays the same when a delivery is retried or redelivered, so use it to ignore duplicates. | | `webhook-timestamp` | Unix time in seconds at which this attempt was signed. | | `webhook-signature` | `v1,` followed by the base64 HMAC-SHA256 signature. | The body is the event envelope: | Field | Meaning | | :--- | :--- | | `id` | Event ID (`evt_…`), the same as `webhook-id`. | | `type` | Event type, for example `import.completed`. | | `api_version` | The payload version, fixed when the endpoint was created. | | `created_at` | When the event happened. This isn't the time of the delivery. | | `workspace_id` | The workspace the event belongs to. | | `data` | A small snapshot of the object: its public ID and a few fields. To get the complete object, read it from the API. | > **Beta** > > While API V2 is in beta, the content of `data` can still change. Its keys use `snake_case`, and the `status` of an import or export has the same values as in API V2, for example `SUCCEEDED` and `PARTIALLY_SUCCEEDED`. Some field names differ from the V2 resource: `import.completed` carries `segments_created` and `segment_texts_updated`, where the import itself has `texts_created` and `texts_updated`. Read the object from the API when you need its V2 representation. ## Verify the signature Check every request before you trust it: 1. Build the signed content: `{webhook-id}.{webhook-timestamp}.{raw body}`. Use the raw body bytes exactly as received, not re-serialized JSON. 2. Compute HMAC-SHA256 over it. The key is your secret without the `whsec_` prefix, base64-decoded. 3. Base64-encode the result and compare it with the value after `v1,` in `webhook-signature`, in constant time. 4. Reject requests whose `webhook-timestamp` is more than a few minutes old, to stop replays. Every attempt is signed with a fresh timestamp, so retries pass this check. ```python import base64 import hashlib import hmac import time def verify(secret: str, headers: dict, body: bytes, tolerance_seconds: int = 300) -> None: timestamp = int(headers["webhook-timestamp"]) if abs(time.time() - timestamp) > tolerance_seconds: raise ValueError("webhook timestamp is too old") key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{headers['webhook-id']}.{timestamp}.".encode() + body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() signatures = [part.split(",", 1)[1] for part in headers["webhook-signature"].split() if part.startswith("v1,")] if not any(hmac.compare_digest(expected, signature) for signature in signatures): raise ValueError("invalid webhook signature") ``` ```javascript import crypto from "node:crypto"; export function verify(secret, headers, rawBody, toleranceSeconds = 300) { const timestamp = Number(headers["webhook-timestamp"]); if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) { throw new Error("webhook timestamp is too old"); } const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const signed = Buffer.concat([Buffer.from(`${headers["webhook-id"]}.${timestamp}.`), rawBody]); const expected = crypto.createHmac("sha256", key).update(signed).digest(); const valid = headers["webhook-signature"].split(" ") .filter((part) => part.startsWith("v1,")) .map((part) => Buffer.from(part.slice(3), "base64")) .some((signature) => signature.length === expected.length && crypto.timingSafeEqual(signature, expected)); if (!valid) { throw new Error("invalid webhook signature"); } } ``` The [Standard Webhooks libraries](https://github.com/standard-webhooks/standard-webhooks) for many languages do the same in one call. ## Respond and retry - Answer with any `2xx` status within 10 seconds. Do the real work after you respond, for example in a queue. - Any other status, a redirect, a timeout or a connection error counts as a failure. LingoHub doesn't follow redirects. - LingoHub retries a failed delivery up to 8 attempts in total: right away, then after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours. - Delivery is **at least once**: the same event can arrive more than once. Ignore events whose `webhook-id` you already processed. - Events can arrive in any order. Use `created_at`, or read the current state from the API, when the order matters. After **15 failed attempts in a row**, LingoHub disables the endpoint (`status` becomes `AUTO_DISABLED`) and stops queuing new events for it. Fix the receiver, then turn the endpoint back on with `POST /v2/webhook-endpoints/{webhookEndpointId}/enable`. Events from the time it was disabled aren't sent afterwards. To stop deliveries yourself, use `POST /v2/webhook-endpoints/{webhookEndpointId}/disable`. Events that happen while the endpoint is off aren't sent either. ## Test, inspect and redeliver - `POST /v2/webhook-endpoints/{webhookEndpointId}/test` sends a `ping` event to that endpoint only. It is queued like any other delivery, and its failed attempts count toward the 15. - `GET /v2/webhook-endpoints/{webhookEndpointId}/deliveries` lists the deliveries of an endpoint, with `status`, `attempt_count`, `next_attempt_at`, `last_response_status`, `last_error` and up to 8 KB of the last failed response body. - `GET /v2/webhook-deliveries/{webhookDeliveryId}` returns one delivery, with the request LingoHub sends for it. - `POST /v2/webhook-deliveries/{webhookDeliveryId}/redeliver` sends a failed delivery again. Testing and redelivering need an enabled endpoint. Otherwise the request fails with `409 conflict`. Deliveries are kept for 30 or 90 days, depending on your plan. ## Rotate the secret `POST /v2/webhook-endpoints/{webhookEndpointId}/rotate-secret` returns a new secret, again shown only once. The old secret stops working immediately, including for retries of earlier deliveries, so update your receiver right after you rotate. Requests already on their way can still carry the old signature. --- # Workflow and recovery guide The compact guide packaged with every API V2 build, written for AI agents and automation. > **Generated from the API** > > This page is the guide that every API V2 build serves at [https://api.lingohub.com/public/api-v2/guide.md](https://api.lingohub.com/public/api-v2/guide.md), published here after each release. It is compact on purpose: AI agents and scripts read it. The other API V2 guides explain the same rules step by step. > **Beta** > > API V2 is in beta. Endpoints, request and response fields, and behavior can still change. Use the LingoHub CLI (`lingohub`) where possible: it is updated together with the API. If you call the HTTP API directly, be prepared to update your integration when V2 changes. See "Beta compatibility" below. The production API origin is `https://api.lingohub.com`. If these files describe another environment, use the origin in the `servers` entry of [the OpenAPI contract](https://api.lingohub.com/public/api-v2/openapi.json) instead. All paths begin with `/v2`. Start with [the operation index](https://api.lingohub.com/public/api-v2/llms.txt). Each group links to the complete [OpenAPI contract](https://api.lingohub.com/public/api-v2/openapi.json), which is authoritative for request fields, required/nullable properties, public enum values, filters and responses. The deployed API describes itself at `GET /v2/openapi.json` (with an API token) and at the public `/public/api-docs/v2`. ## Getting started Create an API key in your workspace's API access settings, or ask a workspace administrator for one. Give it only the workspace and stack permissions your integration needs. Changes to workspace owners are not available in V2. Supply the key using `LINGOHUB_API_KEY`; do not paste it into reports or commit it to a profile file. With the CLI installed, verify your key and its effective access first: ```sh lingohub --json api call getApiKey lingohub --json api call getWorkspace lingohub api operations ``` The CLI calls `https://api.lingohub.com` unless `--base-url` or `LINGOHUB_BASE_URL` selects another origin; set one of them before running these commands against any other environment. The operation inventory is offline; the first two commands call the API. Use `api mcp-tools --operation OPERATION` to inspect the bundled method/path/input schema before a new workflow. Select real IDs from list/read responses, and compare the CLI's bundled contract with the deployed `GET /v2/openapi.json` before relying on a new capability. For content transfer, upload using the documented `createImport` multipart operation, inspect `getImport` and its entries, submit `createExport`, and inspect `getExport` before downloading. An accepted job can still fail or partially commit. Keep recorded IDs so a client interruption does not require resubmitting the mutation. Shared segment edits affect every usage; inspect usages before editing. ## A file workflow with the CLI Set `LINGOHUB_API_KEY` first. The following variables are placeholders for public IDs returned by the API, not sample IDs to submit. `en.json` is your own supported source file and `IMPORT_INTENT`/`EXPORT_INTENT` are unique values you retain for these two intended submissions. ```sh lingohub --json api call listProjects --query limit=20 lingohub --json api call getProject --path projectId="$PROJECT_ID" lingohub --json api call listResources --path branchId="$BRANCH_ID" --query limit=20 lingohub --json --include-headers api upload createImport \ --path branchId="$BRANCH_ID" --upload en.json --form language_code=en \ --idempotency-key "$IMPORT_INTENT" # Read IMPORT_ID from the accepted response, then inspect completion and entries. lingohub --json api wait getImport --path importId="$IMPORT_ID" --timeout 300 lingohub --json api call listImportEntries --path importId="$IMPORT_ID" --query limit=20 lingohub --json --include-headers api call createExport \ --path branchId="$BRANCH_ID" --field 'language_codes=["en"]' \ --idempotency-key "$EXPORT_INTENT" # Read EXPORT_ID from the accepted response. Download to a new destination file. lingohub --json api wait getExport --path exportId="$EXPORT_ID" --timeout 300 lingohub --json api download-export "$EXPORT_ID" --output exported-resources.zip ``` Choose the branch from `getProject`/`listBranches`; do not assume every project has the same branch identity. A timeout stops polling, not the backend job. Reuse `api wait` with the recorded job ID. Inspect all pages of entries after a partial or failed result before deciding what needs correction. Continue each list using `--query cursor="$NEXT_CURSOR"` and unchanged parent/filter/limit until `has_more` is false. Download links expire; the download command obtains a fresh permitted link and never overwrites the destination. For a conditional metadata change, GET the resource with headers first. Copy the complete quoted ETag into `SEGMENT_ETAG`, then send only the intended fields: ```sh lingohub --json --include-headers api call getSegment --path segmentId="$SEGMENT_ID" lingohub --json api call updateSegment --path segmentId="$SEGMENT_ID" \ --if-match "$SEGMENT_ETAG" --field 'description="Label on the sign-in button"' ``` This description is shared across the segment's usages. Use `listSegmentKeys` to discover them. A 412 requires a fresh read and a deliberate decision, not an automatic overwrite. JSON field values need JSON quoting; shell quoting alone does not make a string a JSON value. ## Beta compatibility While V2 is in beta, changes can include renamed operations and fields, tightened input constraints, changed responses and removed operations. The beta has no compatibility or deprecation guarantee. Keep the CLI up to date: its operation inventory and MCP tools are generated from the contract bundled with it, and it is updated together with the API. Operations added after your CLI was built need a newer CLI before you can call them by name. The raw-request command remains available, but it does not check compatibility. If you call the HTTP API directly, keep the OpenAPI contract your integration was built against and compare it with the deployed `GET /v2/openapi.json` to find changes. ## Authentication and identity Send an API token as `Authorization: Bearer `. Browser sessions do not authenticate V2. Use `getApiKey` to discover the current key's scope and effective permissions. Self-managed keys follow their owner's live permissions subject to the shared cap: billing/subscription is at most VIEW and workspace management is NO_ACCESS, including for workspace owners. Current key lifecycle, workspace policy, user permissions and stack scope can change between requests. Use public IDs from responses. Never construct IDs from database numbers or use V1 friendly IDs. Shared segment text edits affect every usage; occurrence key changes apply to the selected file occurrence. Inspect usages before changing shared content. Membership endpoints keep workspace/stack owners protected. ## Constructing requests Use the exact fields and enum values in OpenAPI. Unknown fields/query parameters, duplicate JSON keys and scalar coercion are rejected. Omitted, null, empty and false have distinct meanings. PATCH uses JSON merge-patch; absent fields remain unchanged, and null clears only nullable fields. PUT replaces a complete subresource at its known key. Do not send a body to bodyless actions. Ordinary resource lists use `limit`, `cursor`, `has_more` and `next_cursor`. Keep filters and sort order identical while following a cursor. Stop when `has_more` is false. Use each operation's documented filter schema; filters are not shared indiscriminately across resource groups. Do not infer total counts from a page. ## Filters `filter` is URL-encoded JSON: `where` holds exactly one `_and` or `_or` with an array of clauses, and `sort` lists fields prefixed with `+` (ascending) or `-` (descending). A clause is a nested `_and`/`_or` or one field with one operator. Fields are named `[]` after the list's items. ### Filter operators A clause compares one field with one operator: `{ "": { "": } }`. | Operator | Matches items whose field | Value | |---|---|---| | `_eq`, `_ne` | equals / does not equal the value | one value | | `_in`, `_nin` | is one of / none of the values | non-empty array | | `_lt`, `_lte`, `_gt`, `_gte` | is less than / at most / greater than / at least the value | number or timestamp | | `_within` | lies between the two bounds, both included | `[lower, upper]` | | `_contains`, `_ncontains` | contains / does not contain the text, case-sensitive | text | | `_icontains`, `_nicontains` | contains / does not contain the text, ignoring case | text | | `_starts`, `_ends` | starts / ends with the text, case-sensitive | text | | `_like`, `_nlike` | matches / does not match a pattern, case-sensitive: `%` stands for any text, `_` for one character | text | | `_ilike`, `_nilike` | like `_like` and `_nlike`, ignoring case | text | | `_blank`, `_nblank` | has no text (missing or empty) / has text | `true` | | `_null`, `_nnull` | has no value / has a value | `true` | | `_true`, `_false` | is true / is false | `true` | Which operators a field offers depends on its type: | Field type | Operators | |---|---| | text | `_eq` `_ne` `_contains` `_ncontains` `_icontains` `_nicontains` `_starts` `_ends` `_like` `_nlike` `_ilike` `_nilike` `_blank` `_nblank` | | id, enum | `_eq` `_ne` `_in` `_nin` | | integer | `_eq` `_ne` `_in` `_nin` `_lt` `_lte` `_gt` `_gte` `_within` `_null` `_nnull` | | timestamp | `_eq` `_lt` `_lte` `_gt` `_gte` `_within` `_null` `_nnull` | | boolean | `_true` `_false` | Values have the form the responses show: public ids (`stack_0197c8f2-…`), enum values (`STANDARD_JSON`), and timestamps in RFC 3339 UTC (`2026-01-01T00:00:00Z`). Each list operation shows its own fields in a table under its `filter` parameter in the API reference: the field name, its type, the operators it offers and whether it can sort. More clauses: ```json { "project[type]": { "_in": ["STANDARD_JSON", "I18NEXT_JSON"] } } { "import[created_at]": { "_within": ["2026-11-01T00:00:00Z", "2026-11-30T23:59:59Z"] } } { "invitation[accepted_at]": { "_null": true } } { "branch[is_default]": { "_false": true } } { "key[key]": { "_like": "checkout.%" } } ``` ## Conditional writes and retries For supported writes, GET the specific resource, preserve its opaque strong ETag, then send `If-Match`. A 412 means the representation changed; reread and decide whether to apply the intended change. Unsupported operations reject If-Match. PUT responses omit ETag; GET again for the current validator. ETags provide write preconditions, not a general conditional-GET cache protocol. Use one `Idempotency-Key` for each intended POST operation. Retained successful ordinary results can replay after current authorization. This protection is best effort: loss or expiry of the retained result and the gap between committing an operation and retaining its result prevent an exactly-once guarantee. Never blindly retry an uncertain mutation with a new key. Inspect the affected resource after `idempotency_outcome_unknown` or a lost response. A `idempotency_key_in_use` response supplies Retry-After while another execution is active. Reusing a key for a different request is rejected. One-time signing-secret rotation cannot replay the secret; retained same-key requests report an unknown outcome. If its response is lost, inspect metadata and deliberately rotate again when appropriate. Do not log tokens, signing secrets or complete authorization headers. ## Asynchronous work and errors Creation can acknowledge a resource before its background work is complete. Follow the operation's resource/job identity, poll the documented status and inspect terminal errors and entries. Do not infer success from an accepted request or a download URL alone. Branch initialization must succeed before operations that require ready content. Backups/restores use the documented point-in-time semantics; no branch-merge operation is implied. Errors are RFC 9457 Problem Details with a machine-readable `code`, request correlation and optional field errors. Preserve the response status, code, pointer and request ID when reporting a failure. Invisible resources can return 404. Respect rate-limit headers and Retry-After; rate limiting does not authorize retrying an uncertain mutation. Bulk operations may return per-item failures; inspect every result. ## Backup and restore scope A backup captures branch content using the existing snapshot format. `created_at` is the scheduling time, not the exact capture instant. Inspect `getBackup` and wait for `SUCCEEDED` before using it with `createBackupRestore`; poll `getBackupRestore` for the separate restore outcome. The source backup and destination branch must belong to the same project and have compatible source languages. Choose `language_codes` with the following consequences in mind: | Selection | Existing behavior | |---|---| | Target languages only | Restore those languages on existing keys. Preserve current source text, key metadata/labels and added keys. Missing keys are not recreated. A deleted file can be recreated empty; include the source language if its keys must be restored. | | Source language included | Restore captured source keys and metadata/labels. Recreate missing keys and remove keys added since the snapshot inside backed-up files; removal affects the occurrence in every language, even unselected target languages. | | Unselected target languages | Preserve their current texts on surviving keys. This does not protect an occurrence removed by a source-inclusive restore. | Files added after the snapshot remain. Surviving files keep their current target export path; a recreated file uses its captured path when the snapshot contains one. Backup/restore does not roll back project settings, workflows, images, comments or history to the capture time. `SUCCEEDED` means the restore completed this scope; it does not promise that a target-only restore recovered deleted keys. These are current shared restore semantics, not a new V2 overwrite policy. Automatic schedules use `getBackupSettings` and `setBackupSettings`: replace a complete UTC schedule and a nonempty branch selection in the same project. DAILY uses `period` and `time`; WEEKLY also requires `day_of_week`. Use the current GET ETag for a conditional replacement. `deleteBackupSettings` disables future scheduling; retained backups and already queued work remain. ## Invitation assignment discovery `getInvitationStackAssignment` reads a retained email invitation's stored requested assignment. `NOT_CONFIGURED` means there is no stored assignment; `UNAVAILABLE` means its complete details cannot currently be shown. Only `AVAILABLE` carries the current public role and ordered stack IDs plus stored language defaults. Null and an empty language map retain their distinction. The caller needs workspace members-view permission and settings-management permission on every referenced stack to see those details. Never treat this response as effective access or proof that the invitation was accepted. It creates or changes no assignment and does not permit owner changes. ## Project settings `getProjectSettings` returns every setting of a project in one resource: export and import defaults, file-format options, key normalisation, placeholder recognition and, for a project with an integration, the integration settings. `updateProjectSettings` changes any of them as a JSON merge-patch: send only the sections and fields that change, also inside the sections of `format`. Lists are replaced as a whole, and null removes a `format` section; a section that doesn't exist yet needs all its required fields. All changes are applied together or not at all; one 422 lists every invalid field. Equal values write nothing. Use the GET ETag for If-Match; the PATCH response carries the next one. To go back to the default placeholders, send `placeholders.default_definitions` as `placeholders.definitions`. Changes don't rewrite job-specific overrides; already queued jobs without overrides use the new defaults. ## Reference files The API serves this guide and its reference files at `/public/api-v2/`: `llms.txt`, `guide.md`, `openapi.json` and one page per operation group. They describe the contract of the deployed build, not the permissions of a particular key. Error `type` URLs under `/errors/` are public documentation pages. The CLI also serves the operations as MCP tools over stdio (`lingohub api mcp-serve`). ## Import changes After checking import status and entry outcomes, use `listImportChanges` to see what the import changed: one item per segment and file, with the key change and the text changes in each language you can read. Follow `next_cursor` with the same filter; current ancestry, key access and readable languages apply on every page. `segment_id` and `key_id` turn null once the segment or key is deleted; names, paths and contents stay. Changes may grow during processing and can be filtered by access, so an empty page does not prove an unchanged import. The list does not preview or replay an import and does not change retention policy. ## Disconnecting Git `deleteProjectGitIntegration` removes a project's stored connection, bindings, filters and schedules. GET its configuration first and optionally send the complete response's ETag as `If-Match`. Success is an empty 204. Project content, shared authentication and retained jobs remain; remote webhook cleanup is best effort and this operation does not cancel in-flight work. A stale validator is 412, a concurrent authentication rebind is 409 `conflict` requiring a fresh read, and a missing or already disconnected integration is 404. Current stack settings-management access is required. ## Glossaries, terms and forms Glossaries contain typed terms with independently addressable forms. Translatable forms name a language; untranslatable forms do not. A language has at most one preferred form, and inherited languages reuse a preferred form rather than appearing as independent forms. Use each returned public identity and the published schemas. A form mutation invalidates the complete parent term validator too, so GET the term again before a subsequent conditional update or deletion. The last form is removed by deleting its term. Creation replay and conditional writes retain the general limits described above; several requests do not become one atomic transaction. For retained public API request metadata, use `listApiLogs` and `getApiLog`. Every key reads its own retained requests; workspace API-access view permits other keys' requests in that workspace, while stack-scoped keys remain restricted to their own. Permission and retention changes apply to subsequent requests. The response exposes public IDs, method/path/status and time, not request bodies or authorization headers. Keep the same filter/sort when following cursors; filter to the path of interest because log reads can themselves create log traffic. Invisible or expired detail entries return `resource_not_found`. Style guides use `createStyleGuide` / `listStyleGuides` / `getStyleGuide` / `updateStyleGuide` / `deleteStyleGuide`. Nested global-rule PATCH fields merge; a null individual rule resets to `NOT_SPECIFIED`, while the `rules` object cannot be null. Per-language `setStyleGuideLanguageRules` replaces overrides and clears omitted fields; `setStyleGuideLanguageVariant` requires a regional variant of the addressed general language. GET each known-key resource for its validator after PUT, whose response carries no ETag. Per-language edits also change the parent style-guide validator. Current permissions and workspace visibility apply throughout. ## Provider setup discovery CodeCommit repository and branch discovery returns one native provider page. Omit `limit`; continue with the opaque `next_cursor` and the same authentication/repository until `has_more=false`. Repository pages can contain up to 1,000 items. Branch commit/protection metadata and repository URLs remain null when not supplied by the provider. Native calls preserve the page unchanged; they do not automatically follow it. Azure repository discovery requires `organization` and `project_key` (ID or name from project discovery). It returns the complete selected project's list. GitHub, Azure and CodeCommit directory discovery requires a full immutable `commit_sha` and returns direct children of `path` (empty for root). Azure requires `repository_namespace=organization/project`; CodeCommit has no namespace. Use `getCodeCommitBranch` with `repository_name` and `git_branch` to obtain a selected branch head, then pass that immutable `commit_sha` to directory discovery. Branch names containing slashes remain query values. Use `listAzureOrganizations` to discover the organization before listing its projects; a known organization is also accepted directly. These complete-list endpoints reject `cursor` and `limit`. Upstream bodies are bounded to 2 MiB; complete lists allow up to 1,000 items, except GitHub Contents, where 1,000 results cannot prove completeness and the accepted maximum is 999. Success has `has_more=false` and `next_cursor=null`. Oversized, truncated, continued or non-directory results fail with `502 upstream_error`. Use a narrower directory or known repository/path selection when browsing cannot complete. No stored discovery snapshot or file download is created. Azure Items uses `isSymLink` to distinguish symbolic links from ordinary blob files. Ordinary-file format/language hints are path-only suggestions, not validation of contents or source-language choice. ## Project moves and detachment `moveProject` queues `POST /v2/projects/{projectId}/move` with a destination `stack_id`; the project keeps its own segments, equal texts are not merged. Automations belong to the stack: a moved project runs the destination's, and a detached project's new stack starts with a copy of the shared stack's. `detachProject` queues `POST /v2/projects/{projectId}/detach` without a body. Both return a `PROJECT_MOVE` job and a Location for `getProjectMove`; poll until the status is terminal. A queued request cancels with `MOVE_SOURCE_CHANGED` when its source has changed. Use an Idempotency-Key to recover a lost response while retry protection remains available. A move status is retained with the existing synchronization record; it is not a permanent move history. Inspect the project before resubmitting an uncertain request. The shared workflow is preserved: missing memberships (including owners), language permissions and workspace-key grants are copied; existing destination assignments win. Members/keys may thereby gain access to other destination projects. A private source stack is removed; a private destination is promoted to shared. Moving from a shared stack requires a shared destination. Detachment makes a new private stack, copying shared content for the detached project. Exact-segment deduplication is opt-in; document occurrences are not deduplicated. Moves require settings management on the source project and destination stack; detachment and status reads require settings management on the project. API-key stack scope stays unchanged: a key can lose project/status access after the move, even if the operation succeeded. `stack_id` in the move response always means the project's current stack, including after subsequent moves. A scheduling audit records accepted intent and the requesting actor; it is not proof of completion. --- # API V1 overview The stable API for projects, resource files, exports and repository pushes. > **Stable** > > API V1 is stable and remains supported. ## What you can do - List and create projects, and read their translation status. - Upload resource files, one at a time or as a ZIP archive, and list, download and delete them. - Request exports and poll them for their download links. - Push resource files to a connected repository. - Upload, list and delete context images. ## Base URL `https://api.lingohub.com`. All paths start with `/v1`. ## Authentication API V1 authenticates every request with an API key. See [API keys](/docs/api-keys.md) to create one and choose its permissions. Pass the key in the `Authorization` header with the `Bearer` scheme: ```shell curl https://api.lingohub.com/v1/projects \ -H "Authorization: Bearer $LINGOHUB_API_KEY" ``` New keys start with `lh-api_`. Older keys that start with `lingo_` keep working. A missing or invalid key returns `401`. A key without the permission an endpoint needs returns `403`. ## Workspace and project URLs API V1 addresses workspaces and projects by the slugs in their URLs, `{workspaceUrl}` and `{projectUrl}`: ```text https://api.lingohub.com/v1/{workspaceUrl}/projects/{projectUrl}/... ``` To find the slugs, call [List all projects](/reference/v1/operations/v1projectgetlistofprojects.md). The response has no separate slug fields: the `href` of each project's `self` link is the project's base URL. ```json { "members": [ { "title": "Backend", "links": [ { "rel": "self", "href": "https://api.lingohub.com/v1/wrksp-0/projects/backend" } ] } ], "links": [ { "rel": "self", "href": "https://api.lingohub.com/v1/projects" } ] } ``` Here the workspace slug is `wrksp-0` and the project slug is `backend`. With an API key, the list contains the projects of the key's workspace that the key can access. API V2 identifies workspaces, projects and every other object by public IDs instead of slugs. [Concepts](/docs/concepts.md) explains the objects and their identifiers. ## Conventions - **JSON.** Requests and responses are JSON, except file uploads (`multipart/form-data`) and file downloads. Field names are `camelCase`. A few fields use `snake_case`: `owner_email`, `project_locales`, `created_at` and `updated_at` in the project details, `project_locale` in the resource list, and the query parameters `iso2_slug` and `iso2_code`. - **Branches.** The resource endpoints and the project status accept the query parameter `branch`, the name of a project branch; the export request accepts it as a body field. Without it, LingoHub uses the project's default branch. An unknown name returns `422`. - **Uploads.** An upload returns `201` when LingoHub has accepted the file. The import runs afterwards. - **Exports and pushes.** Both run in the background. An export has a status that you poll; see the recipe [Export translations (API V1)](/recipes/exports.md). ## Errors API V1 uses standard HTTP status codes, in most cases with a JSON error body. See [Errors and status codes](/docs/http-status-codes-error-messages.md). ## Rate limits LingoHub limits requests in two ways: per workspace for every URL that names a workspace (`/v1/{workspaceUrl}/...`), and per IP address for every request. Over a limit, the API answers `429` with the header `Retry-After: 5` and a plain-text body. The `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-RefillRate` headers show the budget that has the least requests left. ## Machine-readable docs - OpenAPI spec: `https://api.lingohub.com/public/api-docs/v1` --- # Errors and status codes Status codes, error bodies and rate limit headers. ## Status codes API V1 returns standard HTTP status codes: | Code | Name | Meaning | | :--- | :--- | :--- | | `200` | OK | The request succeeded. | | `201` | Created | LingoHub accepted an uploaded resource file. The import runs afterwards. | | `304` | Not Modified | A file download whose `If-None-Match` header still matches: the file you hold is current. | | `400` | Bad Request | The request is malformed, for example invalid JSON or a missing part of an upload. | | `401` | Unauthorized | The API key is missing or invalid. | | `403` | Forbidden | The API key doesn't have the permission this endpoint needs. | | `404` | Not Found | The URL is wrong, or the object (for example a project) doesn't exist. | | `405` | Method Not Allowed | The endpoint doesn't support the HTTP method. | | `406` | Not Acceptable | A resource file was uploaded without `path` although the project already has a file of that name under a path: send `path` or `force=true`. Also returned when the `Accept` header asks for a format the endpoint can't produce. | | `413` | Content Too Large | The upload exceeds the maximum size. | | `415` | Unsupported Media Type | The endpoint doesn't accept the `Content-Type` of the request. | | `422` | Unprocessable Entity | The request is well formed but has invalid values, for example an unknown branch or a file extension the project type can't import. | | `429` | Too Many Requests | You exceeded a rate limit. Wait for the seconds in `Retry-After`. | | `500` | Internal Server Error | Something went wrong on LingoHub's side. Contact [support@lingohub.com](mailto:support@lingohub.com) if it persists. | ## Error bodies Most error bodies are JSON. Errors about the input of a request, including a missing or invalid API key, list it in `validationErrors`: ```json { "error": null, "validationErrors": [ { "field": "token", "errors": [ { "code": "authentication.token.invalid", "description": "The token is invalid!", "parameters": {} } ] } ] } ``` Errors that aren't about a specific field use `error` instead: ```json { "error": { "code": "…", "description": "…", "status": "…" }, "validationErrors": null } ``` Use `code` in your error handling; `description` is meant for people. Some errors have other bodies: - A missing workspace, project or other object (`404`) returns `message` and `items`. - Other errors, such as `403` or `500`, return `url`, `message` and `text`. `message` can be empty. - The `406` of a file upload returns `status` and `message`. - The `429` body is plain text, not JSON. Rely on the status code first, and read the body only where your client needs the details. ## Rate limit headers Responses carry the current rate limit budget: | Header | Meaning | | :--- | :--- | | `X-RateLimit-Limit` | Size of the request budget. | | `X-RateLimit-Remaining` | Requests left right now. | | `X-RateLimit-RefillRate` | Rate at which the budget refills. | | `Retry-After` | On `429`: seconds to wait before you retry. | LingoHub keeps one budget per workspace and one per IP address; the headers show the one that has the least requests left. See [Rate limits](/docs/api-v1-overview.md#rate-limits). --- # Supported file formats The file formats LingoHub imports and exports, with their file extensions and project types. LingoHub imports and exports the file formats below. Every format belongs to a project type. You choose the project type when you create a project, and it decides which files the project accepts. The **Project type** column shows the value of `type` in API V2. **Plurals** says whether LingoHub manages the plural forms of a text separately. ## Mobile | Format | File extensions | Project type | Plurals | | --- | --- | --- | --- | | [Android](/docs/android.md) | `.xml` | `ANDROID_XML` | yes | | [Apple iOS strings](/docs/apple-ios.md) | `.strings`, `.stringsdict` | `IOS_STRINGS` | yes, in `.stringsdict` files | | [Xcode String Catalogs](/docs/xcode-string-catalogs.md) | `.xcstrings` | `IOS_STRINGS_CATALOG` | yes | | [Flutter ARB](/docs/flutter-arb.md) | `.arb` | `STANDARD_ARB` | no; ICU plurals stay in the text | | Twine | `.txt` | `TWINE_TXT` | yes | ## Web | Format | File extensions | Project type | Plurals | | --- | --- | --- | --- | | [JSON](/docs/json.md) | `.json` | `STANDARD_JSON` | yes | | [i18next](/docs/i18next.md) | `.json` | `I18NEXT_JSON` | yes | | [Angular (angular-translate)](/docs/angular.md) | `.json` | `ANGULAR_TRANSLATE_JSON` | yes | | [Ember (ember-intl)](/docs/ember-intl.md) | `.json` | `STANDARD_JSON` | yes | | React Intl | `.json` | `REACT_INTL_JSON` | yes | | Vue I18n | `.json` | `VUE_I18N_JSON` | yes | | Chrome extensions (Chrome i18n) | `.json` | `CHROME_I18N_JSON` | no | | [Go i18n](/docs/go-i18n.md) | `.json` | `GO_I18N_JSON` | yes | | [Ruby on Rails YAML](/docs/ruby-on-rails.md) | `.yml`, `.yaml` | `RAILS_YAML` | yes | | [Symfony YAML](/docs/symfony.md) | `.yml`, `.yaml` | `SYMFONY_YAML` | yes | | [PHP define](/docs/php.md) | `.php` | `DEFINE_PHP` | no | | [Gettext PO](/docs/gettext-po.md) | `.po`, `.pot` | `GETTEXT_PO` | yes | | HTML | `.html`, `.xhtml` | `STANDARD_HTML` | no | | Storyblok JSON | `.json` | `STORYBLOK_JSON` | no | ## Desktop and generic | Format | File extensions | Project type | Plurals | | --- | --- | --- | --- | | [Java properties](/docs/properties.md) | `.properties` | `STANDARD_PROPERTIES` | yes | | [RESX and RESW](/docs/reswresx.md) | `.resx`, `.resw` | `WINDOWS_RESX` | no | | [Qt Linguist TS](/docs/qt.md) | `.ts` | `QT_LINGUIST_TS` | no | | [INI](/docs/ini.md) | `.ini` | `STANDARD_INI` | no | | [CSV](/docs/csv.md) | `.csv` | `STANDARD_CSV`, `SINGLE_LANGUAGE_CSV`, `KEY_VALUE_CSV` | no | | [XLIFF](/docs/xliff.md) | `.xliff`, `.xlf` | `STANDARD_XLIFF` (XLIFF 1.2), `STANDARD_XLIFF_2` (XLIFF 2) | yes | ## Documents and subtitles | Format | File extensions | Project type | Plurals | | --- | --- | --- | --- | | [Markdown](/docs/markdown.md) | `.md`, `.markdown` | `STANDARD_MARKDOWN` | no | | [Plain text](/docs/text.md) | `.txt` | `STANDARD_TXT` | no | | Word, PowerPoint and OpenDocument documents | `.docx`, `.pptx`, `.odt`, `.odp` | `DOCUMENT` | no | | [SRT subtitles](/docs/srt-subrip-subtitle.md) | `.srt` | `SUBTITLE_SRT` | no | | [WebVTT subtitles](/docs/vtt.md) | `.vtt` | `SUBTITLE_VTT` | no | ## Choose a project type A project has exactly one project type, and you can't change it after you create the project. Choose the type that matches the files your application loads. If your library keeps its texts in JSON files and has no row of its own, choose JSON. Projects that sync with a platform such as Contentful or Zendesk have project types of their own, which this page does not list. In many formats you can set the status, labels and other metadata of a text from the comments of the file. See [LingoHints](/docs/lingohints_introduction.md). --- # Android Android string resources: strings, string arrays and plurals with their comments and format arguments. LingoHub supports Android string resource files, the standard format for localizing Android apps. LingoHub can export the files of an Android project in the Apple `.strings` format, and the files of an [Apple iOS strings](/docs/apple-ios.md) project as Android XML. ## Format - File extension: `.xml`. - Project type: Android XML (API V2 `type`: `ANDROID_XML`). - The format is based on XML. - LingoHub supports the `string`, `string-array` and `plurals` elements. - An XML comment becomes the description of the element that follows it. - Placeholders are Java format arguments such as `%s` and `%1$d`; see the [Java Formatter reference](https://developer.android.com/reference/java/util/Formatter.html). LingoHub also detects `` elements. - LingoHub imports an element with `translatable="false"` as not translatable, and exports a key that is not translatable with that attribute. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```xml ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Android). ```xml Muss größer oder gleich %d sein Logged in as \"%s\" Logged in as \'%s\' "Logged in as '%s'" "Logged in as \'%s\'" Hello %s!\nYou have got %s unread messages. left Mercury Venus Earth Mars January February March April May June July August September October November December Znaleziono jedną piosenkę. Znaleziono %d piosenki. Znaleziono %d piosenek. ``` ## To consider ### XML escaping on export LingoHub escapes the characters `&` and `<` as `&` and `<`, unless they belong to an entity (for example `"`) or to an HTML tag (for example ``). Otherwise the XML document would not be well formed. If a text contains HTML tags, the HTML export setting of the project decides how LingoHub writes it: - `RAW`: HTML tags stay as they are. Only other `&` and `<` characters are escaped. - `ESCAPE`: every `<`, `>` and `&` is escaped, including those of HTML tags. - `CDATA`: a text that contains HTML tags is wrapped in a `CDATA` section and not escaped. A text that was inside a `CDATA` section when you imported it is exported inside a `CDATA` section, whatever the setting. ### Android escaping on export - LingoHub escapes single quotes as `\'` and double quotes as `\"`, except inside HTML tags. - A value that was enclosed in double quotes on import, such as `" this is some text "`, keeps them, so its whitespace is preserved. LingoHub also encloses a text with leading or trailing whitespace in double quotes. - Newlines are written as `\n`. Inside a `CDATA` section they stay as they are. - In a text with format arguments (`%1$s`, `%d`), LingoHub writes every other percent sign as `%%`. In a text without format arguments, it writes the percent sign as `%`, for example `Save 50% only now!`. If the element has the attribute `formatted="false"`, LingoHub doesn't change percent signs. - The quote and percent rules also apply inside `CDATA` sections. ### Language information In a typical Android project, the file name carries no language (a common name is `strings.xml`); the directory does. LingoHub derives the language from the path, so synchronize your repository with LingoHub to keep the paths. Otherwise you must choose the language when you import a file. ## References - [Android string resources documentation](https://developer.android.com/guide/topics/resources/string-resource) - [Java Formatter syntax for placeholders](https://developer.android.com/reference/java/util/Formatter.html) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Android) --- # Angular (angular-translate) JSON files of angular-translate, a third-party library for AngularJS. [angular-translate](https://angular-translate.github.io/) is a third-party localization library for AngularJS. It keeps its translations in JSON files, which it typically loads with [`$translateProvider.useStaticFilesLoader`](https://angular-translate.github.io/docs/#/guide/12_asynchronous-loading). LingoHub imports and exports these files. > **Third-party library** > > LingoHub does not maintain angular-translate. Its GitHub repository is archived. ## Format - File extension: `.json`. - Project type: Angular-translate JSON (API V2 `type`: `ANGULAR_TRANSLATE_JSON`). - A file contains key-value pairs; nested objects are supported. - LingoHub reads these files by the same rules as [JSON](/docs/json.md) files. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```json { "title": "Title", "_title.comment": "{\"status\": \"TRANSLATED\",\"qc\": {\"min\": \"3\",\"max\": \"20\"},\"labels\": [\"onboarding\"],\"not_translatable\": false}" } ``` ## Example Example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/AngularJS). ```json { "header": "Welcome to our application", "subheader": "Localization with LingoHub", "button": { "save": "Save changes", "cancel": "Cancel" } } ``` ## References - [angular-translate documentation](https://angular-translate.github.io/) - [Asynchronous loading with JSON files](https://angular-translate.github.io/docs/#/guide/12_asynchronous-loading) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/AngularJS) --- # Apple iOS strings Apple .strings and .stringsdict files: keys, comments, format specifiers and plural rules. LingoHub supports `.strings` and `.stringsdict` files for localizing iOS and macOS apps. For `.xcstrings` files, see [Xcode String Catalogs](/docs/xcode-string-catalogs.md). LingoHub can export the files of an Apple iOS strings project as Android XML, and the files of an [Android](/docs/android.md) project in the `.strings` format. ## Format - File extensions: `.strings` and `.stringsdict`. - Project type: IOS Strings (API V2 `type`: `IOS_STRINGS`). A project of this type holds files of both formats. - LingoHub reads UTF-16, UTF-8 and ISO-8859-1 files and exports UTF-8 unless you choose another encoding. ### Strings files - Key-value pairs are delimited with `=` and end with a semicolon `;`. - Enclose keys and values in double quotes. LingoHub also reads keys without quotes. - Newlines can be written directly in a quoted string or escaped as `\n`. - Double quotes must be escaped as `\"`. - Single-line comments begin with `//`. Multi-line comments are enclosed in `/* ... */`. - A comment becomes the description of the key-value pair that follows it. LingoHub exports a comment in the syntax it had on import. - Placeholders follow the [Apple String Format Specifiers reference](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Strings/Articles/formatSpecifiers.html). ### Stringsdict files - The format is an XML property list that holds plural texts according to the [Apple plural rules structure](https://developer.apple.com/documentation/xcode/localizing-strings-that-contain-plurals). - LingoHub supports the rule type `NSStringPluralRuleType`. - LingoHub does not support the rule types `NSStringVariableWidthRuleType` and `NSStringDeviceSpecificRuleType`. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```text /* {"status": "DRAFT","qc": {"min": "3","max": "20"},"labels": ["onboarding"],"not_translatable": false} */ "3fl-p0-pxa.title" = "Title"; ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Apple%20iOS). ### A strings file ```text // This comment is parsed as a header comment. "main.intro" = "The value holds the translated text."; // Generic keys are recommended for cross-platform projects. "page.main.title" = "Titel der Hauptseite"; /* Comments in .strings files can be multi-line, single-line */ // Or a combination of the two. "hello_user" = "Hello %1$s"; // Keys and values can span multiple lines. "welcome.message" = "Welcome back, we have missed you"; // Comments belong to the next key-value pair. "visit.count" = "This is your %1$d visit to our site."; ``` ### A stringsdict file ```xml photos.count NSStringLocalizedFormatKey %#@photos@ photos NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d zero No photos one 1 photo other %d photos days.remaining NSStringLocalizedFormatKey %#@days@ days NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d zero No days remaining one 1 day remaining other %d days remaining ``` ## To consider ### Language information In an Xcode project, the file name carries no language (for example `Localizable.strings`); the directory does. LingoHub derives the language from the path, so synchronize your repository with LingoHub to keep the paths. Otherwise you must choose the language when you import a file. If the path contains a `Base.lproj` directory and names no other language, LingoHub assigns the file to the source language of the project. ### Generic keys Strings files often use the source text as the key. Generic keys, such as `page.main.title`, also work as Android resource names, which helps if you export a project in both formats. ## References - [Apple String Format Specifiers reference](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Strings/Articles/formatSpecifiers.html) - [Apple plural rules documentation](https://developer.apple.com/documentation/xcode/localizing-strings-that-contain-plurals) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Apple%20iOS) --- # Xcode String Catalogs Xcode String Catalog files: all languages in one file, with plural and device variations, comments and states. The String Catalog (`.xcstrings`) is Apple's current localization format for iOS, macOS, watchOS and tvOS apps. It is a JSON file that holds the texts of all languages. String Catalogs replace the older `.strings` and `.stringsdict` files; for those, see [Apple iOS strings](/docs/apple-ios.md). ## Format - File extension: `.xcstrings`. - Project type: IOS Strings Catalog (API V2 `type`: `IOS_STRINGS_CATALOG`). - The format is based on JSON. - A String Catalog is a multi-language file: one file holds the texts of every language. - Placeholders follow the [Apple String Format Specifiers reference](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Strings/Articles/formatSpecifiers.html). - The `comment` of a string becomes the description of the key. - LingoHub imports a string with `"shouldTranslate": false` as not translatable. - The format uses `variations` for texts that differ by context. LingoHub imports: - **Plural variations**: one text per plural form. - **Device variations**: one text per device, for the devices `iphone`, `ipod`, `ipad`, `applewatch`, `appletv`, `applevision`, `mac` and `other`. - **Substitutions**: the substitutions of a string with their own variations. LingoHub maps the `state` of a `stringUnit` to the status of the text: | `state` on import | Status | | --- | --- | | `new` | New | | `stale` | Draft | | `needs_review` | Translated | | `translated` | Approved | On export, LingoHub writes `new` for the statuses New and Blocked, `stale` for Draft, Stale and Rejected, `needs_review` for AI translated, Translated, QA passed and QA flagged, and `translated` for Approved and Not translatable. [LingoHints](/docs/lingohints_introduction.md) can be included in the `comment` of a string: ```json { "sourceLanguage": "en", "strings": { "accessibility_settings": { "comment": "Show accessibility settings. {\"status\": \"DRAFT\",\"qc\": {\"min\": \"3\",\"max\": \"20\"},\"labels\": [\"onboarding\"],\"not_translatable\": false}", "localizations": { "de": { "stringUnit": { "state": "translated", "value": "Barrierefreiheit" } } } } }, "version": "1.0" } ``` ## Example ```json { "sourceLanguage": "en", "strings": { "photos_count": { "extractionState": "manual", "localizations": { "de": { "variations": { "plural": { "one": { "stringUnit": { "state": "translated", "value": "%lld Foto" } }, "other": { "stringUnit": { "state": "translated", "value": "%lld Fotos" } } } } }, "en": { "variations": { "plural": { "one": { "stringUnit": { "state": "translated", "value": "%lld photo" } }, "other": { "stringUnit": { "state": "translated", "value": "%lld photos" } } } } } } }, "welcome_message": { "extractionState": "manual", "localizations": { "de": { "variations": { "device": { "ipad": { "stringUnit": { "state": "translated", "value": "Willkommen auf deinem iPad" } }, "iphone": { "stringUnit": { "state": "translated", "value": "Willkommen auf deinem iPhone" } }, "mac": { "stringUnit": { "state": "translated", "value": "Willkommen auf deinem Mac" } }, "other": { "stringUnit": { "state": "translated", "value": "Willkommen" } } } } }, "en": { "stringUnit": { "state": "translated", "value": "Welcome" } } } } }, "version": "1.0" } ``` ## References - [Apple documentation: Localizing and varying text with a string catalog](https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog) - [Xcode String Catalogs 101 guide](https://belief-driven-design.com/xcode-string-catalogs-101-672f5/) - [Apple iOS strings](/docs/apple-ios.md) --- # Flutter ARB Application Resource Bundle files of Flutter apps: texts, descriptions, placeholders and ICU plurals. Application Resource Bundle (ARB) is a JSON-based file format for localized texts, used mainly in Flutter development. Besides the texts, an ARB file carries attributes such as descriptions and placeholder details, which is what sets it apart from a plain [JSON](/docs/json.md) file. ## Format - File extension: `.arb`. - Project type: Application Resource Bundle (API V2 `type`: `STANDARD_ARB`). - Every text is a key-value pair, as in [JSON](/docs/json.md). - A key prefixed with `@` holds the attributes of the text of that name, for example `"@title_bar": { "description": "..." }`. LingoHub uses `description` as the description of the key and keeps the other attributes for the export. - Placeholders use the `{name}` syntax. - LingoHub supports plurals in the [ICU](https://en.wikipedia.org/wiki/International_Components_for_Unicode) message syntax. The plural forms stay in the text. - LingoHub preserves the global attributes `@@locale`, `@@last_modified`, `@@context` and `@@author`, and custom global attributes that start with `@@x-`. [LingoHints](/docs/lingohints_introduction.md) can be included in the `description` attribute: ```json { "title_bar": "My Cool Home", "@title_bar": { "type": "text", "context": "HomePage", "description": "Page title. {\"status\": \"DRAFT\",\"qc\": {\"min\": \"3\",\"max\": \"20\"},\"labels\": [\"onboarding\"],\"not_translatable\": false}" } } ``` ## Example ```json { "@@last_modified": "2021-02-15T09:58:36.312610", "@@locale": "en_US", "title_bar": "My Cool Home", "@title_bar": { "type": "text", "context": "HomePage", "description": "Page title." }, "ok_message": "Everything works fine.", "pending_costs": "Your pending cost is {COST}", "@pending_costs": { "type": "currency", "context": "HomePage:MainPanel", "description": "Balance statement.", "placeholders": { "COST": { "example": "$123.45", "description": "Cost presented with currency symbol" } } }, "page_home_inbox_count": "{count, plural, one{You have 1 new message} other{You have {count} new messages}}", "@page_home_inbox_count": { "context": "New messages count on the Home screen", "placeholders": { "count": {} } } } ``` ## References - [Internationalizing Flutter apps](https://docs.flutter.dev/ui/internationalization) - [International Components for Unicode (ICU)](https://en.wikipedia.org/wiki/International_Components_for_Unicode) --- # CSV CSV files with one column per language: keys, descriptions, translations and statuses. CSV has no single binding standard: separators, quoting, escaping and encoding vary. LingoHub's CSV format follows RFC 4180. ## Format - File extension: `.csv`. - Project type: CSV Multi Language (API V2 `type`: `STANDARD_CSV`), which this page describes. LingoHub has two more CSV project types: CSV Single Language (`SINGLE_LANGUAGE_CSV`) and CSV Key-Value (`KEY_VALUE_CSV`). - Use [UTF-8](https://en.wikipedia.org/wiki/UTF-8) encoding for the best results. You can export other encodings. - The markup follows the [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180) standard. - New projects export with a semicolon `;` as column separator. You can change it to a comma `,` or a tab in the project settings. - You can enclose values in double or single quotes. - Escape a double quote by doubling it, for example `"Hello, ""LingoHub"""`. - Supported line endings are `LF` and `CRLF`. - Quoted values can span multiple lines. - The first line is the header and names the columns: - **First column**: the key. Name the column `Title`, `Key` or `Id`; you choose the name in the project settings. - **Second column (optional)**: the description of the key. Name the column `Description` or `Comment`; you choose the name in the project settings. - **Further columns**: the texts and their statuses. - A column named by a language code, such as `en` or `pt-BR`, holds the texts of that language. - A column named by the language code and `[status]`, such as `en[status]`, holds the status of each text of that language. Valid values are `NEW`, `DRAFT`, `AI_TRANSLATED`, `TRANSLATED` and `APPROVED`. LingoHub still accepts `PRE_TRANSLATED` for `AI_TRANSLATED`. - The default placeholder syntax is `{placeholder_name}`. To use another syntax, add it in the placeholder settings of the project. [LingoHints](/docs/lingohints_introduction.md) can be included in the description column: ```text "Title","Description","en","pl","de" "settings","General Settings {""status"": ""DRAFT"",""qc"": {""min"": ""4"",""max"": ""30""},""labels"": [""onboarding""],""not_translatable"": false}","Settings","Ustawienia","Einstellungen" ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/CSV). ```text "Title","Description","en","pl","de" "settings","General Settings","Settings","Ustawienia","Einstellungen" "has_placeholders","This example shows the usage of placeholders","Hello {username}","Cześć {username}","Hallo {username}" "quotes","Quotes in content","Hello ""LingoHub""","Cześć ""LingoHub""","Hallo ""LingoHub""" "linebreaks","an example for linebreaks","Here is a linebreak","Oto nowa linia","Hier ist ein Zeilenumbruch" ``` The same file with a status column per language: ```text "Key","Comment","en","pl","de", "en[status]", "pl[status]", "de[status]" "settings","General Settings","Settings","Ustawienia","Einstellungen", "DRAFT", "TRANSLATED", "APPROVED" "has_placeholders","This example shows the usage of placeholders","Hello {username}","Cześć {username}","Hallo {username}", "DRAFT", "TRANSLATED", "APPROVED" "quotes","Quotes in content","Hello ""LingoHub""","Cześć ""LingoHub""","Hallo ""LingoHub""", "DRAFT", "TRANSLATED", "APPROVED" "linebreaks","an example for linebreaks","Here is a linebreak","Oto nowa linia","Hier ist ein Zeilenumbruch", "DRAFT", "TRANSLATED", "APPROVED" ``` ## References - [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/CSV) --- # Ember (ember-intl) JSON translation files of the Ember.js libraries ember-intl and ember-i18n. [ember-intl](https://github.com/ember-intl/ember-intl) and [ember-i18n](https://github.com/jamesarosen/ember-i18n) are third-party libraries for localizing [Ember.js](https://emberjs.com/) applications. LingoHub imports and exports their JSON translation files. > **Third-party libraries** > > LingoHub does not maintain these libraries. The GitHub repository of ember-i18n is archived. ## Format - File extension: `.json`. LingoHub does not import JavaScript translation modules; convert them to JSON first. - Project type: JSON (API V2 `type`: `STANDARD_JSON`). LingoHub has no separate project type for Ember. - LingoHub reads these files by the same rules as [JSON](/docs/json.md) files. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```json { "title": "Title", "_title.comment": "{\"status\": \"TRANSLATED\",\"qc\": {\"min\": \"3\",\"max\": \"20\"},\"labels\": [\"onboarding\"],\"not_translatable\": false}" } ``` ## Example Example files are available on GitHub: - [ember-intl examples](https://github.com/lingohub/Example-Resource-Files/tree/master/Ember%20Intl) - [ember-i18n examples](https://github.com/lingohub/Example-Resource-Files/tree/master/Ember.js) ```json { "header": { "title": "Welcome", "subtitle": "Localization simplified" }, "auth": { "login": "Sign in", "logout": "Sign out" } } ``` ## References - [ember-intl on GitHub](https://github.com/ember-intl/ember-intl) - [ember-intl documentation](https://ember-intl.github.io/ember-intl/) - [ember-i18n on GitHub](https://github.com/jamesarosen/ember-i18n) --- # Gettext PO GNU gettext .po and .pot files: messages, contexts, plural forms and comments. GNU gettext is an internationalization system that many programming languages and frameworks implement, including PHP, Python, C and C#. LingoHub supports its Portable Object (`.po`) files and its Portable Object Template (`.pot`) files. LingoHub imports a `.pot` file as the source language of the project: its `msgid` values are both the keys and the source texts. ## Format - File extensions: `.po` and `.pot`. - Project type: Gettext PO (API V2 `type`: `GETTEXT_PO`). - LingoHub uses the `msgid` as the key. - The `msgstr` holds the text. - If an entry has a `msgctxt`, LingoHub puts it in front of the key, for example `msgctxt/msgid`. - The combination of `msgctxt` and `msgid` must be unique within a file. - Placeholders are printf formatters such as `%s`, `%d` and `%3.4d`. LingoHub also detects ICU message arguments such as `{name}`. - LingoHub supports plural forms that an entry defines with `msgid_plural`. - LingoHub preserves the header of the file and its metadata on export. - LingoHub respects the charset that the header defines, for example `Content-Type: text/plain; charset=UTF-8`. - A comment that begins with `#` becomes the description of the entry that follows it. - LingoHub keeps reference comments (`#:`), extracted comments (`#.`), flag comments (`#,`) and the header comment. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```text # {"status": "DRAFT","qc": {"min": "3","max": "20"},"labels": ["onboarding"],"not_translatable": false} msgctxt "email" msgid "To" msgstr "To" ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Gettext%20PO). ```text # header comment msgid "" msgstr "" "Project-Id-Version: My App 1.0\n" "Report-Msgid-Bugs-To: \n" "Last-Translator: Translator \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=n>1;\n" msgid "mood" msgid_plural "%d moods" msgstr[0] "%d mood" msgstr[1] "%d moods" # The key of this entry is "email/To". msgctxt "email" msgid "To" msgstr "To" # Multi-line values msgid "slogan" msgstr "" "Continuous Translation " "Made Simple" ``` ## Used by - [CakePHP](https://cakephp.org/) - [Django](https://www.djangoproject.com/) ## References - [GNU gettext documentation](https://www.gnu.org/software/gettext/) - [PO file format reference](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html#PO-Files) - [CakePHP internationalization guide](https://book.cakephp.org/5/en/core-libraries/internationalization-and-localization.html) - [Django internationalization documentation](https://docs.djangoproject.com/en/stable/topics/i18n/) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Gettext%20PO) --- # Go i18n JSON files of go-i18n version 1: ids, translations, comments and plural forms. LingoHub supports the JSON format of version 1 of the [go-i18n](https://github.com/nicksnyder/go-i18n) library for Go applications. > **go-i18n version 2** > > This project type is made for the JSON files of go-i18n version 1. For the JSON files of version 2, choose the [JSON](/docs/json.md) project type. ## Format - File extension: `.json`. - Project type: Go I18N JSON (API V2 `type`: `GO_I18N_JSON`). - The file is a JSON array. Every entry is an object with an `id`, which is the key, and a `translation`, which is the text. - For plurals, `translation` is an object with one text per plural form, such as `one` and `other`. - An optional `comment` becomes the description of the key. - go-i18n templates write placeholders as `{{.Placeholder}}`. By default, LingoHub detects printf placeholders such as `%s` and `%d` in projects of this type. You can add other notations, such as double braces, in the placeholder settings of the project. [LingoHints](/docs/lingohints_introduction.md) can be included in the `comment`: ```json [ { "id": "premium_monthly_title", "translation": "{{.Price}} monatlich", "comment": "Monthly subscription price {\"status\": \"DRAFT\",\"qc\": {\"min\": \"3\",\"max\": \"20\"},\"labels\": [\"onboarding\"],\"not_translatable\": false}" } ] ``` ## Example ```json [ { "id": "days_count", "translation": { "one": "{{.Count}} day", "other": "{{.Count}} days" } }, { "id": "height_meters", "translation": { "one": "I am {{.Count}} meter tall.", "other": "I am {{.Count}} meters tall." } }, { "id": "person_greeting", "translation": "Hello {{.Person}}" }, { "id": "unread_email_count", "translation": { "one": "{{.Person}} has {{.Count}} unread email.", "other": "{{.Person}} has {{.Count}} unread emails." } }, { "id": "unread_email_count_timeframe", "translation": { "one": "{{.Person}} has {{.Count}} unread email in the past {{.Timeframe}}.", "other": "{{.Person}} has {{.Count}} unread emails in the past {{.Timeframe}}." } }, { "id": "app_greeting", "translation": "Hello world" } ] ``` ## References - [go-i18n on GitHub](https://github.com/nicksnyder/go-i18n) --- # i18next JSON files of the i18next library: flat and nested keys, plural keys, placeholders and comments. [i18next](https://www.i18next.com/) is an internationalization library for JavaScript, in the browser and in Node.js. LingoHub supports the JSON files of this library. ## Format - File extension: `.json`. - Project type: I18next JSON (API V2 `type`: `I18NEXT_JSON`). - The JSON structure must follow the format that [i18next](https://www.i18next.com/) documents. - LingoHub supports flat and nested structures. - The default placeholder syntax is `{{placeholder}}`. LingoHub also detects nesting references such as `$t(key)`. - LingoHub reads the plural keys of i18next JSON v4 (`key_one`, `key_other`) and of JSON v3 (`key`, `key_plural`). The file format settings of the project select the version; v4 is the default. - A property named `_.comment` next to a key holds the description of that key. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```json { "title": "Title", "_title.comment": "{\"status\": \"TRANSLATED\",\"qc\": {\"min\": \"3\",\"max\": \"20\"},\"labels\": [\"onboarding\"],\"not_translatable\": false}" } ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/I18next). ### Flat structure ```json { "title": "Titel", "body_paragraph": "Dies ist ein Paragraph.", "users_form_submit": "Speichern", "users_salutation": "Hallo {{name}}" } ``` ### Nested structure ```json { "title": "Titel", "body": { "paragraph": "Dies ist ein Paragraph." }, "users": { "form": { "submit": "Speichern" }, "salutation": "Hallo {{name}}" } } ``` ## References - [i18next documentation](https://www.i18next.com/) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/I18next) --- # INI INI files: key-value pairs, sections and comments. The `.ini` format is common for application configuration on many platforms. No single standard defines it, so implementations differ in their delimiters, comment styles and section nesting. LingoHub follows the rules below, which match the most common variations. ## Format - File extension: `.ini`. - Project type: Standard INI (API V2 `type`: `STANDARD_INI`). - Key-value pairs are delimited by `=` or by a colon `:` and end with a newline. - Values must not span multiple lines. - A section declaration has the form `[section]`. - Every key after a section declaration belongs to that section, until the next section begins or the file ends. - LingoHub does not support nested sections. - The section and the name of a key together identify the key. This combination must be unique within the file. - LingoHub detects no placeholders in `.ini` files by default. To have placeholders detected and checked, add their syntax in the placeholder settings of the project. - Comments begin with a hash sign `#` or a semicolon `;`. - A comment becomes the description of the key-value pair that directly follows it. LingoHub does not keep a comment that a blank line or a section declaration follows. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```ini ; {"status": "DRAFT","qc": {"min": "3","max": "20"},"labels": ["onboarding"],"not_translatable": false} hello_user = Hello stranger! ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/INI). ```ini ; LingoHub does not keep this comment: a blank line follows it. ; LingoHub does not keep this comment either: a section declaration follows it. [section_1] # Comments in .ini files can start with a hash sign. hello_user = Hello stranger! [section_2] ; This key belongs to section_2. welcome_message = Welcome back, we have missed you. ; Comments that span several lines belong to the next key-value pair, ; provided that no blank line interrupts them. visit_count = This is your millionth visit to our site. ``` ## References - [INI file overview on Wikipedia](https://en.wikipedia.org/wiki/INI_file) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/INI) --- # JSON JSON files of key-value pairs: flat and nested keys, arrays, plurals, placeholders and comments. Many JavaScript libraries and frameworks keep the texts of an application in JSON files. The JSON project type of LingoHub reads JSON files of key-value pairs, flat or nested. ## Format - File extension: `.json`. - Project type: JSON (API V2 `type`: `STANDARD_JSON`). - The format follows the JSON specification: keys and values must be enclosed in double quotes. - LingoHub supports flat and nested structures, and arrays. - An object whose property names are all plural forms (`zero`, `one`, `two`, `few`, `many`, `other`) and whose values are texts is read as one text with plural forms. - The default placeholder syntax is `{{placeholder}}`. LingoHub also detects `%(name)` and `$t(key)`. - A property named `_.comment` next to a key holds the description of that key. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```json { "title": "Title", "_title.comment": "{\"status\": \"TRANSLATED\",\"qc\": {\"min\": \"3\",\"max\": \"20\"},\"labels\": [\"onboarding\"],\"not_translatable\": false}" } ``` ## Related project types Some libraries that use JSON files have a project type of their own, with the placeholder syntax of the library: [i18next](/docs/i18next.md), [angular-translate](/docs/angular.md), [go-i18n](/docs/go-i18n.md), React Intl, Vue I18n and Chrome extensions. See [Supported file formats](/docs/file-types.md) for all of them. Choose the JSON project type if your library is not among them. ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/JSON). ### Flat structure ```json { "title": "Titel", "body_paragraph": "Dies ist ein Paragraph.", "users_form_submit": "Speichern", "users_salutation": "Hallo {{name}}" } ``` ### Nested structure ```json { "title": "Titel", "body": { "paragraph": "Dies ist ein Paragraph." }, "users": { "form": { "submit": "Speichern" }, "salutation": "Hallo {{name}}" } } ``` ## References - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/JSON) --- # Markdown Markdown files: paragraphs, headings, lists and code blocks, with front matter and HTML comments. Markdown is a lightweight markup language for formatted text, widely used for documentation, blog posts and readme files. LingoHub translates Markdown files and keeps their structure. ## Format - File extensions: `.md` and `.markdown`. - Project type: Markdown (API V2 `type`: `STANDARD_MARKDOWN`). - LingoHub divides the content into segments by paragraph. - A heading, a list, a code block and an indented block are one segment each. The same holds for a container block between `:::` lines and an equation block between `$$` lines. - LingoHub preserves the front matter on import and export. - LingoHub stores an HTML comment (``) as the description of the block that follows it. ## Example ````markdown --- title: Sample Document --- # Introduction This is a paragraph. It spans multiple lines. * List item 1. * List item 2. This item spans multiple lines. ## Section 1 Code example: ```python print("Hello, world!") ``` ```` ## References - [Markdown guide](https://www.markdownguide.org/) --- # PHP define PHP files with define statements: keys, values, printf placeholders and comments. PHP has no single standard for internationalization. [Gettext PO](/docs/gettext-po.md) is common; a simpler approach keeps the texts as key-value pairs in `define` statements. LingoHub supports these PHP files. ## Format - File extension: `.php`. - Project type: PHP Define (API V2 `type`: `DEFINE_PHP`). - Every `define` statement must end with a semicolon `;`. - Write the keyword as `define` or `DEFINE`. - Keys and values can be enclosed in single or double quotes. - Placeholders are printf formatters such as `%s`, `%d` and `%3.4d`. - A comment that begins with `#` becomes the description of the statement that follows it. - Newlines can be escaped as `\n`. - LingoHub supports `define` statements on a single line; statements that span several lines are not supported. - LingoHub keeps the content before the first and after the last `define` statement and exports it again. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```php # {"status": "DRAFT","qc": {"min": "3","max": "20"},"labels": ["onboarding"],"not_translatable": false} define('logoff', 'Log off'); ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Php%20Define). ```php ``` ## References - [PHP documentation](https://www.php.net/docs.php) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Php%20Define) --- # Java properties Java .properties files: key-value pairs, comments, line continuations and placeholders. The `.properties` format is widely used for configuration and localization, above all on the Java platform. No universal standard defines it. LingoHub follows the dialect of `java.util.ResourceBundle` and accepts common variations. ## Format - File extension: `.properties`. - Project type: Properties (API V2 `type`: `STANDARD_PROPERTIES`). - Key-value pairs are delimited by `=` and end with a newline. - Whitespace can surround the `=` delimiter. LingoHub does not support `:` as a delimiter. - To continue a value on the next line, end the line with a backslash `\`. - Newlines can be escaped as `\n`. - Placeholders use the `{name}` syntax of ICU messages, for example `{username}` or `{0}`. - Comments begin with a hash sign `#` or an exclamation mark `!`. - A comment becomes the description of the key-value pair that follows it. - LingoHub reads UTF-8, ISO-8859-1 and UTF-16 files and exports UTF-8 by default. If you turn on the escaping of characters in the export settings, LingoHub writes non-ASCII characters as `\uXXXX` escapes, which suits environments that read `.properties` files as [ISO-8859-1](https://en.wikipedia.org/wiki/ISO_8859-1). [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```properties # {"status": "DRAFT","qc": {"min": "3","max": "20"},"labels": ["onboarding"],"not_translatable": false} hello_user = Hello {username} ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Java). ```properties # This comment is interpreted as a header comment. # Values can continue to the next line using a backslash. welcome_message = Welcome back, \ we have missed you. # Comments that span several lines belong to the next key-value pair, # provided that no blank line interrupts them. visit_count = This is your {visit} visit to our site. ! Comments in .properties files can start with an exclamation mark. hello_user = Hello {username} escaped_newline = A newline can be escaped \n with a backslash. charset_escaped = Muss gr\u00F6sser gleich {value} sein. ``` ## Used by - [Java](https://www.java.com/) (through `java.util.ResourceBundle`) - [Spring Framework](https://spring.io/) - [Grails](https://grails.org/) - [GWT](https://www.gwtproject.org/) - [Play Framework](https://www.playframework.com/) ## References - [Java internationalization guide](https://docs.oracle.com/javase/tutorial/i18n/) - [java.util.ResourceBundle API documentation](https://docs.oracle.com/javase/8/docs/api/java/util/ResourceBundle.html) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Java) --- # Qt Linguist TS Qt Linguist .ts files: messages, contexts, comments and placeholders. Qt Linguist is the tool that Qt provides for translating Qt applications. It stores translations in TS files, which LingoHub imports and exports. ## Format - File extension: `.ts`. - Project type: QT Linguist TS (API V2 `type`: `QT_LINGUIST_TS`). - The format is based on XML. - LingoHub keeps the `language` attribute of the `` element and writes it back on export. It does not read the language of the file from it: the language comes from the file name or path, or from the language you choose on upload. - Every `` element is one key. It must contain a `` and a `` element. - LingoHub uses the content of the `` element as the key. - If `` elements are grouped in a `` element, the content of its `` element prefixes their keys. - The `` element holds the text. - The content of the `` element becomes the description of the key. - LingoHub preserves `` elements and exports them as they were imported. - Placeholders are a percent sign followed by a number, for example `%1`. [LingoHints](/docs/lingohints_introduction.md) can be included in the `` element: ```xml hello_user Hallo %1 {"status": "DRAFT","qc": {"min": "3","max": "20"},"labels": ["onboarding"],"not_translatable": false} ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Qt). ```xml Page translations_example Beispiel für Übersetzungen hello_user Hallo %1 installscript dynamic_page_message Diese Seite wurde dynamisch erzeugt. ``` ## References - [Qt Linguist manual: TS file format](https://doc.qt.io/qt-6/linguist-ts-file-format.html) - [Qt Linguist manual](https://doc.qt.io/qt-6/qtlinguist-index.html) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Qt) --- # RESX and RESW .resx and .resw files of .NET and Windows apps: data entries, values and comments. RESX and RESW are the resource file formats of C# and .NET applications. The two formats use different file extensions, `.resx` and `.resw`, and the same XML structure. ## Format - File extensions: `.resx` and `.resw`. - Project type: Windows RESX (API V2 `type`: `WINDOWS_RESX`). - The format is based on XML; the XML rules for encoding, escaping and quoting apply. - LingoHub does not evaluate an XSD schema in the file. - The `name` attribute of a `` element is the key. - The content of the `` element is the text. - The `` element of a `` element is the description of the key. LingoHub keeps XML comments (``) between the entries and writes them back on export. - Placeholders use the `{name}` syntax, for example `{name}` or `{0}`. - If a `` element has the attribute `xml:space="preserve"`, LingoHub keeps the exact content of the `` element, including whitespace. [LingoHints](/docs/lingohints_introduction.md) can be included in the `` element: ```xml Authentifikation fehlgeschlagen {"status": "DRAFT","qc": {"min": "3","max": "20"},"labels": ["onboarding"],"not_translatable": false} ``` ## Example More example files are available on GitHub for [RESX](https://github.com/lingohub/Example-Resource-Files/tree/master/RESX) and [RESW](https://github.com/lingohub/Example-Resource-Files/tree/master/RESW). ```xml Authentifikation fehlgeschlagen This comment is the description of the "auth_failed" key. Verrechenbar Pausen Titel Hallo {0} ``` ## References - [Work with .resx files programmatically (Microsoft)](https://learn.microsoft.com/en-us/dotnet/core/extensions/work-with-resx-files-programmatically) - [Localize strings (Windows App SDK, Microsoft)](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/mrtcore/localize-strings) - [RESX examples](https://github.com/lingohub/Example-Resource-Files/tree/master/RESX) and [RESW examples](https://github.com/lingohub/Example-Resource-Files/tree/master/RESW) on GitHub --- # Ruby on Rails YAML YAML locale files of Ruby on Rails: nested keys, arrays, comments and placeholders. Ruby on Rails applications keep their texts in YAML locale files, as the [Rails I18n guide](https://guides.rubyonrails.org/i18n.html) describes. LingoHub imports and exports these files. ## Format - File extensions: `.yml` and `.yaml`. - Project type: Rails YAML (API V2 `type`: `RAILS_YAML`). - Key-value pairs are delimited by a colon `:`. - Values can be enclosed in single or double quotes. - LingoHub supports YAML block scalars, such as `|` for multi-line values. - LingoHub supports the nested structure that Rails I18n uses. - The first level of the file must be the language code, for example `en`. LingoHub reads the language of the file from it. - A comment that begins with a hash sign `#` and directly precedes a key-value pair becomes the description of that key. - The default placeholder syntax is `%{name}`. - LingoHub imports and exports YAML arrays. - The default encoding of Rails I18n files is [UTF-8](https://en.wikipedia.org/wiki/UTF-8). - LingoHub exports syntactically correct YAML. The quoting or the array syntax can differ from the imported file. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```yaml en: header: # {"status": "DRAFT","qc": {"min": "3","max": "20"},"labels": ["onboarding"],"not_translatable": false} hello_user: Hello %{user} ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Ruby%20on%20Rails). ```yaml en: header: hello_user: Hello %{user} welcome: "Welcome to LingoHub! This is your %{visit_count} visit." about: features_list: - Reach billions with your apps. - Support for Android and iOS. - GitHub integration. status_options: ['new', 'processed', 'completed'] description: | This is a multi-line value in YAML. ``` ## References - [Rails I18n guide](https://guides.rubyonrails.org/i18n.html) - [YAML 1.2 specification](https://yaml.org/spec/1.2/spec.html) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Ruby%20on%20Rails) --- # SRT subtitles SubRip subtitle files: subtitle blocks with their timecodes. SRT (SubRip Subtitle) is a simple subtitle format that most video players and editing tools support. ## Format - File extension: `.srt`. - Project type: SRT Subtitle (API V2 `type`: `SUBTITLE_SRT`). - A file consists of sequentially numbered subtitle blocks. - Every block has four parts: 1. **Sequence number**: a number that gives the order of the subtitle. 2. **Timecode**: the start and end times, separated by `-->`, in the form `hours:minutes:seconds,milliseconds`. LingoHub accepts the comma `,` and the period `.` as separator of the milliseconds. 3. **Text**: the subtitle, which can span several lines. 4. **Blank line**: a mandatory blank line that ends the block. - LingoHub uses the timecode line, for example `00:00:00,000 --> 00:00:02,500`, as the key. - An SRT file has no comments, so [LingoHints](/docs/lingohints_introduction.md) are not available. ## Example ```text 1 00:00:00,000 --> 00:00:02,500 Welcome to the example subtitle file. 2 00:00:03,000 --> 00:00:06,000 This is a multi-line subtitle entry. 3 00:00:07,000 --> 00:00:10,500 SRT files make it easy to add captions to your videos. ``` ## Used by - YouTube (captions) - Facebook (video captions) - VLC media player - Video editing software such as Adobe Premiere and Final Cut Pro ## References - [SubRip format overview on Wikipedia](https://en.wikipedia.org/wiki/SubRip) --- # Symfony YAML YAML translation files of Symfony: flat and nested keys, arrays, comments and placeholders. Symfony applications can keep their translations in YAML files. LingoHub imports and exports these files. For the YAML files of Ruby on Rails, see [Ruby on Rails YAML](/docs/ruby-on-rails.md). ## Format - File extensions: `.yml` and `.yaml`. - Project type: Symfony YAML (API V2 `type`: `SYMFONY_YAML`). - Keys can be the source text or generic identifiers. - Key-value pairs are delimited by a colon `:`. - Values can be enclosed in single or double quotes. - LingoHub reads nested keys as groups and YAML sequences as arrays. - A comment that begins with a hash sign `#` and directly precedes a key-value pair becomes the description of that key. - By default, LingoHub detects ICU message arguments such as `{name}` and the notation `#name#` as placeholders. You can change the notations in the placeholder settings of the project. - LingoHub exports syntactically correct YAML. The quoting or the escaping can differ from the imported file. [LingoHints](/docs/lingohints_introduction.md) can be included in a comment: ```yaml # {"status": "DRAFT","qc": {"min": "3","max": "20"},"labels": ["onboarding"],"not_translatable": false} header.hello_user: Hello {username} ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Symfony2). ```yaml # Generic key example author.name.not_blank: Please enter an author name. # Placeholder example users.salutation: "Hello {username}" # Source text used as key "Symfony is great": "J'aime Symfony" # Nested keys navigation: home: Home settings: Settings ``` ## References - [Symfony translation documentation](https://symfony.com/doc/current/translation.html) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/Symfony2) --- # Plain text Plain text files: one segment per paragraph, with line breaks and empty lines kept. LingoHub supports plain text files for content that has no key-value structure, such as longer prose. ## Format - File extension: `.txt`. - Project type: Standard TXT (API V2 `type`: `STANDARD_TXT`). - LingoHub divides the content into segments by paragraph. One or more empty lines separate two paragraphs. - LingoHub preserves the empty lines between paragraphs. - A paragraph that spans several lines is one segment, and its line breaks are preserved. - A text file has no keys and no comments: LingoHub identifies a paragraph by its position, and [LingoHints](/docs/lingohints_introduction.md) are not available. - LingoHub uses [UTF-8](https://en.wikipedia.org/wiki/UTF-8) encoding by default. ## Example ```text This is the first paragraph. It spans multiple lines. This is the second paragraph. This is the third paragraph. It also spans multiple lines and contains more text. ``` --- # WebVTT subtitles WebVTT subtitle files: cues with their timecodes, NOTE, STYLE and REGION blocks. VTT (Web Video Text Tracks) is the subtitle format of HTML5 video. Besides the subtitles, it can carry styling, positioning and notes. ## Format - File extension: `.vtt`. - Project type: VTT Subtitle (API V2 `type`: `SUBTITLE_VTT`). - The file must begin with the `WEBVTT` header. - Blank lines separate the subtitle blocks, which are called cues. - A cue consists of: 1. **Cue identifier** (optional): a name for the cue, for example `intro`. 2. **Timecode**: the start and end times, separated by `-->`, in the form `mm:ss.ttt` or `hh:mm:ss.ttt`. LingoHub accepts the period `.` and the comma `,` as separator of the milliseconds. 3. **Cue settings** (optional): settings such as `align:start size:50%` after the timecode, on the same line. 4. **Payload**: the text of the subtitle. - LingoHub uses the timecode line with its settings, for example `00:00:00.000 --> 00:00:02.500 align:start`, as the key. - LingoHub reads a `NOTE` block above a cue as the description of that cue. - LingoHub preserves `STYLE` and `REGION` blocks on import and export. ## Example ```text WEBVTT NOTE This is a comment block in a VTT file. intro_slide 00:00:00.000 --> 00:00:10.700 Welcome to the presentation. main_content 00:00:10.700 --> 00:00:47.600 This is the main payload of the subtitle. ``` ## Used by - The HTML5 `` element - Web video players such as Video.js and Plyr ## References - [W3C WebVTT specification](https://www.w3.org/TR/webvtt1/) - [MDN Web Docs: WebVTT API](https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API) --- # XLIFF XLIFF files: translation units, notes, groups, states and inline placeholders. XLIFF (XML Localization Interchange File Format) is an XML-based standard for exchanging localization data between tools and services. Many development environments, such as [Xcode](https://developer.apple.com/xcode/), can export and import XLIFF files. ## Format - File extensions: `.xliff` and `.xlf`. - Project types: Standard XLIFF 1 (API V2 `type`: `STANDARD_XLIFF`) for [XLIFF 1.2](https://docs.oasis-open.org/xliff/v1.2/os/xliff-core.html) files and Standard XLIFF 2 (`STANDARD_XLIFF_2`) for XLIFF 2 files. This page describes XLIFF 1.2. - An XLIFF file can hold the source language and a target language. - The `` element names the languages in its `source-language` and `target-language` attributes. LingoHub uses these attributes to assign the texts to the languages of the project. - The `` element is mandatory; the `` element is optional. - LingoHub uses the `id` attribute of a `` element as the key. If the resname setting of the project is on, it uses the `resname` attribute where one exists. - `` elements can be grouped in `` elements. The `id` of a group then prefixes the keys in it. - The first `` element of a `` becomes the description of the key. LingoHub keeps further notes. - LingoHub preserves the attributes of the elements, `` elements and the `
` on export. - Placeholders are the inline elements of XLIFF, such as ``, ``, ``, `` and ``, for example `{0,number}`. LingoHub maps the `state` attribute of the `` element to the status of the translation, and back on export: | `state` | Status | | --- | --- | | `new` | New | | `needs-translation` | Draft | | `x-prefilled` | AI translated | | `translated` | Translated | | `final` | Approved | [LingoHints](/docs/lingohints_introduction.md) can be included in a `` element: ```xml Box "{0}" is blue. Box {0,number} ist blau. {"status": "DRAFT","qc": {"min": "3","max": "20"},"labels": ["onboarding"],"not_translatable": false} ``` ## Example More example files are available on [GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/XLIFF). ```xml Box 12 is {0,number} inches high. Box Zwölf ist {0,number} Zoll hoch. Box "{0}" is blue. Box {0,number} ist blau. Hello username XliffInfo.java 34 ``` ## References - [OASIS XLIFF technical committee](https://groups.oasis-open.org/communities/tc-community-home2?CommunityKey=3d0f1f56-8477-4b53-9b14-018dc7d3eecf) - [XLIFF 1.2 specification](https://docs.oasis-open.org/xliff/v1.2/os/xliff-core.html) - [LingoHub example resource files on GitHub](https://github.com/lingohub/Example-Resource-Files/tree/master/XLIFF) --- # LingoHints Set the status, labels, quality check limits and the not-translatable flag from the comments of your files. Some file formats can store a status or a flag next to a text; many cannot. LingoHints close this gap. A LingoHint is a small JSON object between `` and `` that you write into the comment or description of a key. When LingoHub imports the file, it applies the hint and stores the text in front of it as the description. LingoHub reads LingoHints on import, in every file format that has comments or descriptions. Exported files contain the description only: LingoHub does not write `` blocks. ## What a LingoHint can set - The [status](https://help.lingohub.com/en/articles/6683154-how-to-manage-your-translation-workflow-using-statuses) of a text. - The [labels](https://help.lingohub.com/en/articles/6684070-what-can-i-do-with-labels) of a segment. - The length limits of the [quality checks](https://help.lingohub.com/en/articles/6684626-what-are-quality-checks). - Whether a segment is translatable. ## Example This [JSON](/docs/json.md) file carries a LingoHint in the comment of the key `salutation`: ```json { "user": { "salutation": "Hallo {{name}}", "_salutation.comment": "Is used to say Hello {\"status\": \"NEW\",\"qc\": {\"min\": \"0\",\"max\": \"20\"},\"labels\": [\"onboarding\"],\"not_translatable\": false}" } } ``` LingoHub stores `Is used to say Hello` as the description and reads this hint: ```json { "status": "NEW", "qc": { "min": "0", "max": "20" }, "labels": [ "onboarding" ], "not_translatable": false } ``` Write the hint at the end of the comment: LingoHub does not keep text that follows ``. The page of each file format shows where its comments go; see [Supported file formats](/docs/file-types.md). ## Properties Every property is optional. ### Status The `status` property sets the status of the imported text. See the [Help Center](https://help.lingohub.com/en/articles/6683154-how-to-manage-your-translation-workflow-using-statuses) for the meaning of the statuses. Valid values are: - `NEW` - `DRAFT` - `AI_TRANSLATED` - `TRANSLATED` - `APPROVED` - `BLOCKED` - `STALE` - `REJECTED` The values are not case-sensitive. LingoHub still accepts `PRE_TRANSLATED` for `AI_TRANSLATED`, and ignores a value it does not know. ```json {"status": "DRAFT"} ``` ### Labels The `labels` property assigns one or more labels to a segment. A label belongs to the segment, so it applies in every language. LingoHub creates the labels that do not exist yet. ```json {"labels": ["invalid", "duplicate"]} ``` ### Not translatable The `not_translatable` property marks a segment as not translatable (`true`) or translatable (`false`). ```json {"not_translatable": true} ``` ### Quality check limits The `qc` property sets the minimum and maximum number of characters that the quality checks accept for the text. Write `min` and `max` as strings. ```json {"qc": {"min": "0", "max": "3"}} ``` ## Errors A LingoHint that is not valid JSON does not fail the import. LingoHub ignores the hint, keeps the description and records an error in the log of the import. --- # Import a file (API V2) Upload a resource file to a project, wait for the import job and check the result of every file. ## Find the branch Files belong to a branch. `GET /v2/projects/{projectId}` returns the project's `default_branch_id`. **Shell** ```shell # Step 1: Find the project's default branch BRANCH_ID=$(curl -s "$API/projects/$PROJECT_ID" -H "$AUTH" | jq -r '.default_branch_id') ``` **Python** ```python # Step 1: Find the project's default branch project = session.get(f"{API}/projects/{os.environ['PROJECT_ID']}").json() branch_id = project["default_branch_id"] ``` ## Upload the file Send the file as `multipart/form-data`. `language_code` is optional: without it, LingoHub detects the language from the file name and path. A `.zip` file is imported as an archive. The `Idempotency-Key` makes a retry of this request safe. The response is `202 Accepted` with the import job; its ID is `data.id`. **Shell** ```shell # Step 2: Upload the file IMPORT_KEY=$(uuidgen) IMPORT_ID=$(curl -s -X POST "$API/branches/$BRANCH_ID/imports" \ -H "$AUTH" \ -H "Idempotency-Key: $IMPORT_KEY" \ -F "file=@en.json" \ -F "language_code=en" | jq -r '.data.id') ``` **Python** ```python # Step 2: Upload the file with open("en.json", "rb") as file: job = session.post( f"{API}/branches/{branch_id}/imports", headers={"Idempotency-Key": str(uuid.uuid4())}, files={"file": ("en.json", file)}, data={"language_code": "en"}, ).json() import_id = job["data"]["id"] ``` ## Wait for the import Poll the import until its `status` is no longer `QUEUED` or `PROCESSING`. `SUCCEEDED` means every file was imported; `PARTIALLY_SUCCEEDED` and `FAILED` need a look at the entries. **Shell** ```shell # Step 3: Wait until the import has finished while true; do STATUS=$(curl -s "$API/imports/$IMPORT_ID" -H "$AUTH" | jq -r '.status') case "$STATUS" in QUEUED|PROCESSING) sleep 2 ;; *) break ;; esac done echo "Import $IMPORT_ID finished: $STATUS" ``` **Python** ```python # Step 3: Wait until the import has finished while True: status = session.get(f"{API}/imports/{import_id}").json()["status"] if status not in ("QUEUED", "PROCESSING"): break time.sleep(2) print(f"Import {import_id} finished: {status}") ``` ## Check every file Each entry is one file of the upload in one language, with its own `status`. `UNCHANGED` means the file hasn't changed since its last import, so the import left it alone. After the first file that fails, the remaining entries are `SKIPPED`. A list returns 20 entries by default, so read every page. **Shell** ```shell # Step 4: Check the result of every file, on every page PAGE=$(curl -s -G "$API/imports/$IMPORT_ID/entries" -H "$AUTH" --data-urlencode "limit=100") while true; do echo "$PAGE" | jq -r '.data[] | "\(.file_path) [\(.language_code)]: \(.status)"' [ "$(echo "$PAGE" | jq -r '.has_more')" = "true" ] || break CURSOR=$(echo "$PAGE" | jq -r '.next_cursor') PAGE=$(curl -s -G "$API/imports/$IMPORT_ID/entries" -H "$AUTH" \ --data-urlencode "limit=100" --data-urlencode "cursor=$CURSOR") done ``` **Python** ```python # Step 4: Check the result of every file, on every page params = {"limit": 100} page = session.get(f"{API}/imports/{import_id}/entries", params=params).json() while True: for entry in page["data"]: print(f"{entry['file_path']} [{entry['language_code']}]: {entry['status']}") if not page["has_more"]: break page = session.get(f"{API}/imports/{import_id}/entries", params={**params, "cursor": page["next_cursor"]}).json() ``` ## Complete example **Shell** ```shell # Requires: LINGOHUB_API_KEY and PROJECT_ID (a public ID such as pr_0197c8f2-...) API=https://api.lingohub.com/v2 AUTH="Authorization: Bearer $LINGOHUB_API_KEY" # Step 1: Find the project's default branch BRANCH_ID=$(curl -s "$API/projects/$PROJECT_ID" -H "$AUTH" | jq -r '.default_branch_id') # Step 2: Upload the file IMPORT_KEY=$(uuidgen) IMPORT_ID=$(curl -s -X POST "$API/branches/$BRANCH_ID/imports" \ -H "$AUTH" \ -H "Idempotency-Key: $IMPORT_KEY" \ -F "file=@en.json" \ -F "language_code=en" | jq -r '.data.id') # Step 3: Wait until the import has finished while true; do STATUS=$(curl -s "$API/imports/$IMPORT_ID" -H "$AUTH" | jq -r '.status') case "$STATUS" in QUEUED|PROCESSING) sleep 2 ;; *) break ;; esac done echo "Import $IMPORT_ID finished: $STATUS" # Step 4: Check the result of every file, on every page PAGE=$(curl -s -G "$API/imports/$IMPORT_ID/entries" -H "$AUTH" --data-urlencode "limit=100") while true; do echo "$PAGE" | jq -r '.data[] | "\(.file_path) [\(.language_code)]: \(.status)"' [ "$(echo "$PAGE" | jq -r '.has_more')" = "true" ] || break CURSOR=$(echo "$PAGE" | jq -r '.next_cursor') PAGE=$(curl -s -G "$API/imports/$IMPORT_ID/entries" -H "$AUTH" \ --data-urlencode "limit=100" --data-urlencode "cursor=$CURSOR") done ``` **Python** ```python import os import time import uuid import requests API = "https://api.lingohub.com/v2" session = requests.Session() session.headers["Authorization"] = f"Bearer {os.environ['LINGOHUB_API_KEY']}" # Step 1: Find the project's default branch project = session.get(f"{API}/projects/{os.environ['PROJECT_ID']}").json() branch_id = project["default_branch_id"] # Step 2: Upload the file with open("en.json", "rb") as file: job = session.post( f"{API}/branches/{branch_id}/imports", headers={"Idempotency-Key": str(uuid.uuid4())}, files={"file": ("en.json", file)}, data={"language_code": "en"}, ).json() import_id = job["data"]["id"] # Step 3: Wait until the import has finished while True: status = session.get(f"{API}/imports/{import_id}").json()["status"] if status not in ("QUEUED", "PROCESSING"): break time.sleep(2) print(f"Import {import_id} finished: {status}") # Step 4: Check the result of every file, on every page params = {"limit": 100} page = session.get(f"{API}/imports/{import_id}/entries", params=params).json() while True: for entry in page["data"]: print(f"{entry['file_path']} [{entry['language_code']}]: {entry['status']}") if not page["has_more"]: break page = session.get(f"{API}/imports/{import_id}/entries", params={**params, "cursor": page["next_cursor"]}).json() ``` ## Responses ```json { "object_type": "JOB", "job_type": "IMPORT", "data": { "object_type": "IMPORT", "id": "rin_0197c8f2-5a6b-7cde-8f12-3456789abcde", "branch_id": "prb_0197c8f2-5a6b-7cde-8f12-3456789abcde", "status": "QUEUED", "status_details": null, "git_source": null, "texts_created": 0, "texts_updated": 0, "keys_deactivated": 0, "keys_reactivated": 0, "keys_renamed": 0, "created_at": "2026-11-04T10:30:00.123Z", "updated_at": "2026-11-04T10:30:00.123Z" } } ``` ```json { "object_type": "LIST", "has_more": false, "next_cursor": null, "data": [ { "object_type": "IMPORT_ENTRY", "id": "rie_0197c8f2-5a6b-7cde-8f12-3456789abcde", "import_id": "rin_0197c8f2-5a6b-7cde-8f12-3456789abcde", "resource_id": "rc_0197c8f2-5a6b-7cde-8f12-3456789abcde", "file_path": "en.json", "language_code": "en", "status": "SUCCEEDED", "status_details": null, "file_size_bytes": 2048, "created_at": "2026-11-04T10:30:00.123Z", "updated_at": "2026-11-04T10:30:04.512Z" } ] } ``` --- # Export translations (API V2) Request an export of a branch, wait for the job and download the file. ## Find the branch Exports run on a branch. `GET /v2/projects/{projectId}` returns the project's `default_branch_id`. **Shell** ```shell # Step 1: Find the project's default branch BRANCH_ID=$(curl -s "$API/projects/$PROJECT_ID" -H "$AUTH" | jq -r '.default_branch_id') ``` **Python** ```python # Step 1: Find the project's default branch project = session.get(f"{API}/projects/{os.environ['PROJECT_ID']}").json() branch_id = project["default_branch_id"] ``` ## Request the export Choose the languages with `language_codes`. To export every language, send an empty JSON object (`{}`): the request must have a JSON body. The response is `202 Accepted` with the export job; its ID is `data.id`. **Shell** ```shell # Step 2: Request the export EXPORT_KEY=$(uuidgen) EXPORT_ID=$(curl -s -X POST "$API/branches/$BRANCH_ID/exports" \ -H "$AUTH" \ -H "Idempotency-Key: $EXPORT_KEY" \ -H "Content-Type: application/json" \ -d '{"language_codes": ["de", "fr"]}' | jq -r '.data.id') ``` **Python** ```python # Step 2: Request the export job = session.post( f"{API}/branches/{branch_id}/exports", headers={"Idempotency-Key": str(uuid.uuid4())}, json={"language_codes": ["de", "fr"]}, ).json() export_id = job["data"]["id"] ``` ## Wait for the export Poll the export until its `status` is no longer `QUEUED` or `PROCESSING`. Only a `SUCCEEDED` export has a `download_url`. An export stops at the first file that fails and ends `FAILED`; the files exported before that can still be downloaded one by one from `GET /v2/exports/{exportId}/entries`. **Shell** ```shell # Step 3: Wait until the export has finished while true; do EXPORT=$(curl -s "$API/exports/$EXPORT_ID" -H "$AUTH") STATUS=$(echo "$EXPORT" | jq -r '.status') case "$STATUS" in QUEUED|PROCESSING) sleep 2 ;; *) break ;; esac done echo "Export $EXPORT_ID finished: $STATUS" ``` **Python** ```python # Step 3: Wait until the export has finished while True: export = session.get(f"{API}/exports/{export_id}").json() if export["status"] not in ("QUEUED", "PROCESSING"): break time.sleep(2) print(f"Export {export_id} finished: {export['status']}") ``` ## Download the file `download_url` is a pre-signed link to a ZIP with the exported files. It expires at `download_url_expires_at`. If it has expired, read the export again for a fresh link. **Shell** ```shell # Step 4: Download the file DOWNLOAD_URL=$(echo "$EXPORT" | jq -r '.download_url // empty') if [ -n "$DOWNLOAD_URL" ]; then curl -s -o translations.zip "$DOWNLOAD_URL" fi ``` **Python** ```python # Step 4: Download the file if export["download_url"]: with requests.get(export["download_url"], stream=True) as download: with open("translations.zip", "wb") as file: for chunk in download.iter_content(chunk_size=65536): file.write(chunk) ``` ## Complete example **Shell** ```shell # Requires: LINGOHUB_API_KEY and PROJECT_ID (a public ID such as pr_0197c8f2-...) API=https://api.lingohub.com/v2 AUTH="Authorization: Bearer $LINGOHUB_API_KEY" # Step 1: Find the project's default branch BRANCH_ID=$(curl -s "$API/projects/$PROJECT_ID" -H "$AUTH" | jq -r '.default_branch_id') # Step 2: Request the export EXPORT_KEY=$(uuidgen) EXPORT_ID=$(curl -s -X POST "$API/branches/$BRANCH_ID/exports" \ -H "$AUTH" \ -H "Idempotency-Key: $EXPORT_KEY" \ -H "Content-Type: application/json" \ -d '{"language_codes": ["de", "fr"]}' | jq -r '.data.id') # Step 3: Wait until the export has finished while true; do EXPORT=$(curl -s "$API/exports/$EXPORT_ID" -H "$AUTH") STATUS=$(echo "$EXPORT" | jq -r '.status') case "$STATUS" in QUEUED|PROCESSING) sleep 2 ;; *) break ;; esac done echo "Export $EXPORT_ID finished: $STATUS" # Step 4: Download the file DOWNLOAD_URL=$(echo "$EXPORT" | jq -r '.download_url // empty') if [ -n "$DOWNLOAD_URL" ]; then curl -s -o translations.zip "$DOWNLOAD_URL" fi ``` **Python** ```python import os import time import uuid import requests API = "https://api.lingohub.com/v2" session = requests.Session() session.headers["Authorization"] = f"Bearer {os.environ['LINGOHUB_API_KEY']}" # Step 1: Find the project's default branch project = session.get(f"{API}/projects/{os.environ['PROJECT_ID']}").json() branch_id = project["default_branch_id"] # Step 2: Request the export job = session.post( f"{API}/branches/{branch_id}/exports", headers={"Idempotency-Key": str(uuid.uuid4())}, json={"language_codes": ["de", "fr"]}, ).json() export_id = job["data"]["id"] # Step 3: Wait until the export has finished while True: export = session.get(f"{API}/exports/{export_id}").json() if export["status"] not in ("QUEUED", "PROCESSING"): break time.sleep(2) print(f"Export {export_id} finished: {export['status']}") # Step 4: Download the file if export["download_url"]: with requests.get(export["download_url"], stream=True) as download: with open("translations.zip", "wb") as file: for chunk in download.iter_content(chunk_size=65536): file.write(chunk) ``` ## Responses ```json { "object_type": "EXPORT", "id": "reg_0197c8f2-5a6b-7cde-8f12-3456789abcde", "branch_id": "prb_0197c8f2-5a6b-7cde-8f12-3456789abcde", "language_codes": [ "de", "fr" ], "status": "SUCCEEDED", "status_details": null, "git_result": null, "download_url": "https://storage.lingohub.com/exports/reg_0197c8f2-5a6b-7cde-8f12-3456789abcde?token=abc", "download_url_expires_at": "2026-11-05T10:30:00.123Z", "created_at": "2026-11-04T10:30:00.123Z", "updated_at": "2026-11-04T10:30:06.204Z" } ``` --- # Update a translation safely (API V2) Find a key, read its segment with the German text and the ETag, and change the text only if nobody changed the segment in the meantime. ## Find the key List the keys of a resource file with a `filter` on `key[key]`. A key points to the segment that holds its texts (`segment_id`) and names its project (`project_id`). `RESOURCE_ID` is the ID of the file: `GET /v2/branches/{branchId}/resources` lists the files of a branch. **Shell** ```shell # Step 1: Find the key KEY=$(curl -s -G "$API/resources/$RESOURCE_ID/keys" -H "$AUTH" \ --data-urlencode 'filter={"where":{"_and":[{"key[key]":{"_eq":"login"}}]}}' \ | jq '.data[0]') SEGMENT_ID=$(echo "$KEY" | jq -r '.segment_id') PROJECT_ID=$(echo "$KEY" | jq -r '.project_id') ``` **Python** ```python # Step 1: Find the key keys = session.get( f"{API}/resources/{os.environ['RESOURCE_ID']}/keys", params={"filter": '{"where":{"_and":[{"key[key]":{"_eq":"login"}}]}}'}, ).json() key = keys["data"][0] ``` ## Read the text and its ETag The texts are part of the segment. Read the segment and limit it to the language you want with `language_codes`. Keep the `ETag` header: it identifies the version of the whole segment, in all its languages. **Shell** ```shell # Step 2: Read the segment with its German text, and keep its ETag curl -s -G -D headers.txt -o segment.json "$API/segments/$SEGMENT_ID" -H "$AUTH" \ --data-urlencode "language_codes=de" ETAG=$(grep -i '^etag:' headers.txt | cut -d' ' -f2- | tr -d '\r') jq '.texts.de.variants' segment.json ``` **Python** ```python # Step 2: Read the segment with its German text, and keep its ETag response = session.get(f"{API}/segments/{key['segment_id']}", params={"language_codes": "de"}) etag = response.headers["ETag"] text = response.json()["texts"]["de"] ``` ## Update it conditionally Send the new text under `texts`, by language code, with `If-Match` set to the ETag. `project_id` selects the project whose placeholder settings and automations process the text; without it, LingoHub uses the project of the segment's oldest key. `device` and `plural_form` default to `OTHER`, so a plain text is one variant with only `content`. The segment is shared, so the change applies to every key that uses it. The status of the text after the change follows the project's automations. To set the status yourself, for example to approve the text, use `POST /v2/segments/{segmentId}/transition`. **Shell** ```shell # Step 3: Update it only if the segment is still the version you read STATUS=$(curl -s -o update.json -w '%{http_code}' -X PATCH "$API/segments/$SEGMENT_ID?project_id=$PROJECT_ID" \ -H "$AUTH" \ -H "If-Match: $ETAG" \ -H "Content-Type: application/merge-patch+json" \ -d '{"texts": {"de": {"variants": [{"content": "Anmelden"}]}}}') ``` **Python** ```python # Step 3: Update it only if the segment is still the version you read update = session.patch( f"{API}/segments/{key['segment_id']}", params={"project_id": key["project_id"]}, headers={"If-Match": etag, "Content-Type": "application/merge-patch+json"}, json={"texts": {"de": {"variants": [{"content": "Anmelden"}]}}}, ) ``` ## Handle a conflict `412 precondition_failed` means the segment changed after you read it: a text in any language, its description or its labels. Read it again and decide whether your change still applies; never overwrite it blindly. **Shell** ```shell # Step 4: Handle a conflict if [ "$STATUS" = "412" ]; then echo "The segment changed since it was read. Read it again before you retry." fi ``` **Python** ```python # Step 4: Handle a conflict if update.status_code == 412: print("The segment changed since it was read. Read it again before you retry.") else: update.raise_for_status() ``` ## Complete example **Shell** ```shell # Requires: LINGOHUB_API_KEY and RESOURCE_ID (a public ID such as rc_0197c8f2-...) API=https://api.lingohub.com/v2 AUTH="Authorization: Bearer $LINGOHUB_API_KEY" # Step 1: Find the key KEY=$(curl -s -G "$API/resources/$RESOURCE_ID/keys" -H "$AUTH" \ --data-urlencode 'filter={"where":{"_and":[{"key[key]":{"_eq":"login"}}]}}' \ | jq '.data[0]') SEGMENT_ID=$(echo "$KEY" | jq -r '.segment_id') PROJECT_ID=$(echo "$KEY" | jq -r '.project_id') # Step 2: Read the segment with its German text, and keep its ETag curl -s -G -D headers.txt -o segment.json "$API/segments/$SEGMENT_ID" -H "$AUTH" \ --data-urlencode "language_codes=de" ETAG=$(grep -i '^etag:' headers.txt | cut -d' ' -f2- | tr -d '\r') jq '.texts.de.variants' segment.json # Step 3: Update it only if the segment is still the version you read STATUS=$(curl -s -o update.json -w '%{http_code}' -X PATCH "$API/segments/$SEGMENT_ID?project_id=$PROJECT_ID" \ -H "$AUTH" \ -H "If-Match: $ETAG" \ -H "Content-Type: application/merge-patch+json" \ -d '{"texts": {"de": {"variants": [{"content": "Anmelden"}]}}}') # Step 4: Handle a conflict if [ "$STATUS" = "412" ]; then echo "The segment changed since it was read. Read it again before you retry." fi ``` **Python** ```python import os import time import uuid import requests API = "https://api.lingohub.com/v2" session = requests.Session() session.headers["Authorization"] = f"Bearer {os.environ['LINGOHUB_API_KEY']}" # Step 1: Find the key keys = session.get( f"{API}/resources/{os.environ['RESOURCE_ID']}/keys", params={"filter": '{"where":{"_and":[{"key[key]":{"_eq":"login"}}]}}'}, ).json() key = keys["data"][0] # Step 2: Read the segment with its German text, and keep its ETag response = session.get(f"{API}/segments/{key['segment_id']}", params={"language_codes": "de"}) etag = response.headers["ETag"] text = response.json()["texts"]["de"] # Step 3: Update it only if the segment is still the version you read update = session.patch( f"{API}/segments/{key['segment_id']}", params={"project_id": key["project_id"]}, headers={"If-Match": etag, "Content-Type": "application/merge-patch+json"}, json={"texts": {"de": {"variants": [{"content": "Anmelden"}]}}}, ) # Step 4: Handle a conflict if update.status_code == 412: print("The segment changed since it was read. Read it again before you retry.") else: update.raise_for_status() ``` ## Responses ```json { "object_type": "SEGMENT", "id": "seg_0197c8f2-5a6b-7cde-8f12-3456789abcde", "stack_id": "stack_0197c8f2-5a6b-7cde-8f12-3456789abcde", "is_plural": false, "description": "Label on the sign-in button", "is_not_translatable": false, "not_translatable_reason": null, "label_ids": [], "texts": { "en": { "is_source": true, "status": "APPROVED", "stage": "DONE", "variants": [ { "content": "Sign in", "device": "OTHER", "plural_form": "OTHER" } ], "updated_at": "2026-09-29T08:00:00.123Z", "content_updated_at": "2026-09-29T08:00:00.123Z" }, "de": { "is_source": false, "status": "TRANSLATED", "stage": "NEEDS_REVIEW", "variants": [ { "content": "Anmelden", "device": "OTHER", "plural_form": "OTHER" } ], "updated_at": "2026-11-04T10:30:00.123Z", "content_updated_at": "2026-11-04T10:30:00.123Z" } }, "created_at": "2026-09-29T08:00:00.123Z", "updated_at": "2026-09-29T08:00:00.123Z" } ``` ```json { "type": "https://api.lingohub.com/errors/precondition-failed", "title": "Precondition failed", "status": 412, "detail": "The resource no longer matches If-Match. Read its current representation and ETag, then decide whether to retry the change.", "instance": "/v2/segments/seg_0197c8f2-5a6b-7cde-8f12-3456789abcde", "code": "precondition_failed", "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } ``` --- # List with filters and cursors (API V2) Select items with a filter, sort them, and read every page of a list. ## Build the filter A filter is JSON: `where` selects items, `sort` orders them (`+` ascending, `-` descending). Each list documents its fields in its `filter` parameter. **Shell** ```shell # Step 1: Build the filter: projects whose name contains "app", sorted by name FILTER='{"where":{"_and":[{"project[name]":{"_icontains":"app"}}]},"sort":["+project[name]"]}' ``` **Python** ```python # Step 1: Build the filter: projects whose name contains "app", sorted by name params = { "filter": json.dumps({ "where": {"_and": [{"project[name]": {"_icontains": "app"}}]}, "sort": ["+project[name]"], }), "limit": 100, } ``` ## Read the first page Send the filter URL-encoded. `limit` can be up to 100. **Shell** ```shell # Step 2: Read the first page PAGE=$(curl -s -G "$API/projects" -H "$AUTH" \ --data-urlencode "filter=$FILTER" --data-urlencode "limit=100") ``` **Python** ```python # Step 2: Read the first page page = session.get(f"{API}/projects", params=params).json() ``` ## Follow the cursor Repeat the request with `cursor` set to `next_cursor` until `has_more` is `false`. Keep the filter and limit unchanged while you follow a cursor. **Shell** ```shell # Step 3: Follow the cursor until the last page while true; do echo "$PAGE" | jq -r '.data[] | "\(.id) \(.name)"' [ "$(echo "$PAGE" | jq -r '.has_more')" = "true" ] || break CURSOR=$(echo "$PAGE" | jq -r '.next_cursor') PAGE=$(curl -s -G "$API/projects" -H "$AUTH" \ --data-urlencode "filter=$FILTER" --data-urlencode "limit=100" \ --data-urlencode "cursor=$CURSOR") done ``` **Python** ```python # Step 3: Follow the cursor until the last page while True: for project in page["data"]: print(project["id"], project["name"]) if not page["has_more"]: break page = session.get(f"{API}/projects", params={**params, "cursor": page["next_cursor"]}).json() ``` ## Complete example **Shell** ```shell # Requires: LINGOHUB_API_KEY API=https://api.lingohub.com/v2 AUTH="Authorization: Bearer $LINGOHUB_API_KEY" # Step 1: Build the filter: projects whose name contains "app", sorted by name FILTER='{"where":{"_and":[{"project[name]":{"_icontains":"app"}}]},"sort":["+project[name]"]}' # Step 2: Read the first page PAGE=$(curl -s -G "$API/projects" -H "$AUTH" \ --data-urlencode "filter=$FILTER" --data-urlencode "limit=100") # Step 3: Follow the cursor until the last page while true; do echo "$PAGE" | jq -r '.data[] | "\(.id) \(.name)"' [ "$(echo "$PAGE" | jq -r '.has_more')" = "true" ] || break CURSOR=$(echo "$PAGE" | jq -r '.next_cursor') PAGE=$(curl -s -G "$API/projects" -H "$AUTH" \ --data-urlencode "filter=$FILTER" --data-urlencode "limit=100" \ --data-urlencode "cursor=$CURSOR") done ``` **Python** ```python import os import time import uuid import requests API = "https://api.lingohub.com/v2" session = requests.Session() session.headers["Authorization"] = f"Bearer {os.environ['LINGOHUB_API_KEY']}" import json # Step 1: Build the filter: projects whose name contains "app", sorted by name params = { "filter": json.dumps({ "where": {"_and": [{"project[name]": {"_icontains": "app"}}]}, "sort": ["+project[name]"], }), "limit": 100, } # Step 2: Read the first page page = session.get(f"{API}/projects", params=params).json() # Step 3: Follow the cursor until the last page while True: for project in page["data"]: print(project["id"], project["name"]) if not page["has_more"]: break page = session.get(f"{API}/projects", params={**params, "cursor": page["next_cursor"]}).json() ``` ## Responses ```json { "object_type": "LIST", "has_more": true, "next_cursor": "1uO9WTLnYqGAtIWkjDmz4VuJZWLkWMxXIH4Hkp2DTuRtPNQYBpkF6Q", "data": [ { "object_type": "PROJECT", "id": "pr_0197c8f2-5a6b-7cde-8f12-3456789abcde", "stack_id": "stack_0197c8f2-5a6b-7cde-8f12-3456789abcde", "default_branch_id": "prb_0197c8f2-5a6b-7cde-8f12-3456789abcde", "name": "My App", "website": "myapp.dev", "ai_context": null, "type": "STANDARD_JSON", "color": "#FF5733", "created_at": "2026-01-15T10:30:00.123Z", "updated_at": "2026-06-20T14:45:00.123Z" } ] } ``` --- # Export translations (API V1) Request an export of a project, wait until it has finished and download the ZIP file. ## Request the export `POST /v1/{workspaceUrl}/projects/{projectUrl}/exports` starts an export; LingoHub writes the files in the background. The body is optional: without it, the export contains every file in every language. - `filePaths` limits the export to certain files. A path names a file in all its languages, so it carries the placeholder `%{locale}` where the language stands, for example `config/locales/%{locale}/messages.yml`. Replace the path of the sample with a path of your project; [Get project resource file status](/reference/v1/operations/v1projectgetprojectstatus.md) returns the paths in `filePathWithLocalePlaceholder`. A path the project doesn't have returns `404`. - `iso2Slugs` limits the export to certain languages. The response carries the `id` of the export. Its `status` starts as `SCHEDULED`. **Shell** ```shell # Step 1: Request the export EXPORT=$(curl -sS --fail-with-body -X POST "$API/exports" \ -H "$AUTH" \ -H "Content-Type: application/json" \ -d '{ "filePaths": ["config/locales/%{locale}/messages.yml"], "iso2Slugs": ["en", "de"] }') || { echo "$EXPORT"; exit 1; } EXPORT_ID=$(echo "$EXPORT" | jq -r '.id') echo "Export requested: $EXPORT_ID" ``` **Python** ```python # Step 1: Request the export response = session.post( f"{API}/exports", json={ "filePaths": ["config/locales/%{locale}/messages.yml"], "iso2Slugs": ["en", "de"], }, ) response.raise_for_status() export_id = response.json()["id"] print(f"Export requested: {export_id}") ``` ## Wait for the export Read the export with `GET .../exports/{id}` until its `status` is no longer `NEW`, `SCHEDULED` or `PROCESSING`. The final statuses are `SUCCESS`, `ERROR` and `SKIPPED`. **Shell** ```shell # Step 2: Wait until the export has finished while true; do EXPORT=$(curl -sS --fail-with-body "$API/exports/$EXPORT_ID" -H "$AUTH") || { echo "$EXPORT"; exit 1; } STATUS=$(echo "$EXPORT" | jq -r '.status') case "$STATUS" in NEW|SCHEDULED|PROCESSING) sleep 2 ;; *) break ;; esac done echo "Export $EXPORT_ID finished: $STATUS" ``` **Python** ```python # Step 2: Wait until the export has finished while True: response = session.get(f"{API}/exports/{export_id}") response.raise_for_status() export = response.json() if export["status"] not in ("NEW", "SCHEDULED", "PROCESSING"): break time.sleep(2) print(f"Export {export_id} finished: {export['status']}") ``` ## Download the ZIP file Only an export with the status `SUCCESS` has a file. `downloadUrl` is a pre-signed link to the ZIP file that is valid for 24 hours; every read of the export returns a fresh link. If the export failed, `errorDetails` says why. **Shell** ```shell # Step 3: Download the ZIP file if [ "$STATUS" != "SUCCESS" ]; then echo "$EXPORT" | jq -r '.errorDetails' exit 1 fi curl -sS -o export.zip "$(echo "$EXPORT" | jq -r '.downloadUrl')" ``` **Python** ```python # Step 3: Download the ZIP file if export["status"] != "SUCCESS": sys.exit(export["errorDetails"] or "The export produced no file.") with requests.get(export["downloadUrl"], stream=True) as download: download.raise_for_status() with open("export.zip", "wb") as file: for chunk in download.iter_content(chunk_size=65536): file.write(chunk) ``` ## Complete example **Shell** ```shell # Requires: LINGOHUB_API_KEY, WORKSPACE_URL and PROJECT_URL (the two slugs of the project's API URL) API="https://api.lingohub.com/v1/$WORKSPACE_URL/projects/$PROJECT_URL" AUTH="Authorization: Bearer $LINGOHUB_API_KEY" # Step 1: Request the export EXPORT=$(curl -sS --fail-with-body -X POST "$API/exports" \ -H "$AUTH" \ -H "Content-Type: application/json" \ -d '{ "filePaths": ["config/locales/%{locale}/messages.yml"], "iso2Slugs": ["en", "de"] }') || { echo "$EXPORT"; exit 1; } EXPORT_ID=$(echo "$EXPORT" | jq -r '.id') echo "Export requested: $EXPORT_ID" # Step 2: Wait until the export has finished while true; do EXPORT=$(curl -sS --fail-with-body "$API/exports/$EXPORT_ID" -H "$AUTH") || { echo "$EXPORT"; exit 1; } STATUS=$(echo "$EXPORT" | jq -r '.status') case "$STATUS" in NEW|SCHEDULED|PROCESSING) sleep 2 ;; *) break ;; esac done echo "Export $EXPORT_ID finished: $STATUS" # Step 3: Download the ZIP file if [ "$STATUS" != "SUCCESS" ]; then echo "$EXPORT" | jq -r '.errorDetails' exit 1 fi curl -sS -o export.zip "$(echo "$EXPORT" | jq -r '.downloadUrl')" ``` **Python** ```python # Requires: LINGOHUB_API_KEY, WORKSPACE_URL and PROJECT_URL (the two slugs of the project's API URL) import os import sys import time import requests API = f"https://api.lingohub.com/v1/{os.environ['WORKSPACE_URL']}/projects/{os.environ['PROJECT_URL']}" session = requests.Session() session.headers["Authorization"] = f"Bearer {os.environ['LINGOHUB_API_KEY']}" # Step 1: Request the export response = session.post( f"{API}/exports", json={ "filePaths": ["config/locales/%{locale}/messages.yml"], "iso2Slugs": ["en", "de"], }, ) response.raise_for_status() export_id = response.json()["id"] print(f"Export requested: {export_id}") # Step 2: Wait until the export has finished while True: response = session.get(f"{API}/exports/{export_id}") response.raise_for_status() export = response.json() if export["status"] not in ("NEW", "SCHEDULED", "PROCESSING"): break time.sleep(2) print(f"Export {export_id} finished: {export['status']}") # Step 3: Download the ZIP file if export["status"] != "SUCCESS": sys.exit(export["errorDetails"] or "The export produced no file.") with requests.get(export["downloadUrl"], stream=True) as download: download.raise_for_status() with open("export.zip", "wb") as file: for chunk in download.iter_content(chunk_size=65536): file.write(chunk) ``` ## Responses ```json { "id": "reg_18USq6822XIv-19847171", "status": "SCHEDULED", "resourceExports": [], "errorDetails": null, "filePath": null, "downloadUrl": null, "triggerType": "API_V1", "createdAt": "2026-01-15T10:30:00.000+00:00" } ``` ```json { "id": "reg_18USq6822XIv-19847171", "status": "SUCCESS", "resourceExports": [ { "filePath": "config/locales/en/messages.yml", "iso2Slug": "en", "status": "SUCCESS", "downloadUrl": "https://lingohub-...s3.amazonaws.com/..." }, { "filePath": "config/locales/de/messages.yml", "iso2Slug": "de", "status": "SUCCESS", "downloadUrl": "https://lingohub-...s3.amazonaws.com/..." } ], "errorDetails": null, "filePath": "files.zip", "downloadUrl": "https://lingohub-...s3.amazonaws.com/...", "triggerType": "API_V1", "createdAt": "2026-01-15T10:30:00.000+00:00" } ```