{ "openapi": "3.0.0", "info": { "title": "Loco API Reference", "description": "Browse the Loco API endpoints, and try them directly from your browser. You'll need an API key for authentication.\n\nRead: About the API.", "version": "1.0.29" }, "servers": [ { "url": "https://localise.biz" } ], "paths": { "/api/assets/{id}.json": { "get": { "tags": [ "assets" ], "summary": "Get a project asset", "description": "Gets a single asset in currently authenticated project", "operationId": "getAsset", "parameters": [ { "$ref": "#/components/parameters/uri_asset" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/asset_404" } } }, "delete": { "tags": [ "assets" ], "summary": "Delete an asset permanently", "description": "Deletes an asset from the currently authenticated project.\n\n**Warning**: This will permanently delete all translations made of this asset across all locales.", "operationId": "deleteAsset", "parameters": [ { "$ref": "#/components/parameters/uri_asset" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/asset_404" } } }, "patch": { "tags": [ "assets" ], "summary": "Modify a single asset", "description": "Modifies the properties of an asset in the currently authenticated project and returns the full, modified object.\n\nTo modify tags, see the tagging endpoints. To modify plural forms, see the plural endpoints", "operationId": "patchAsset", "parameters": [ { "$ref": "#/components/parameters/uri_asset" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Partial asset data to update", "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/asset_404" } } } }, "/api/assets/{id}/tags": { "post": { "tags": [ "assets" ], "summary": "Tag an asset", "description": "Tags an asset with a new or existing term. If the tag doesn't exist it will be created.", "operationId": "tagAsset", "parameters": [ { "$ref": "#/components/parameters/uri_asset" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Name of new or existing tag", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/asset_404" } } } }, "/api/assets/{id}/tags/{tag}.json": { "delete": { "tags": [ "assets" ], "summary": "Untag an asset", "description": "Removes a single tag from the given asset.", "operationId": "untagAsset", "parameters": [ { "$ref": "#/components/parameters/uri_asset" }, { "name": "tag", "in": "path", "description": "Term to remove from asset's tags", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/asset_404" } } } }, "/api/assets/{id}/plurals": { "get": { "tags": [ "assets" ], "summary": "Get plural forms of an asset", "description": "Lists all assets that are a plural form of the current asset.\n\nThis list does **not** include the singular form itself.", "operationId": "getAssetPlurals", "parameters": [ { "$ref": "#/components/parameters/uri_asset" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/asset_404" } } }, "post": { "tags": [ "assets" ], "summary": "Add a new plural form of an existing asset", "description": "Creates a translatable asset that's a plural form of an existing asset.\n\nThe singular form asset specified as {id} must already exist, but the plural form will be created as a new asset.\n\nYou can bind an existing asset as the new plural by specifying {pid} in which case {text} will be ignored.", "operationId": "createPlural", "parameters": [ { "$ref": "#/components/parameters/uri_asset" } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "properties": { "text": { "description": "Initial source language translation of new asset (ignored when linking existing asset)", "type": "string" }, "pid": { "description": "Unique asset ID for new or existing plural form (up to 999 bytes)", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/asset_404" } } } }, "/api/assets/{id}/plurals/{pid}.json": { "delete": { "tags": [ "assets" ], "summary": "Unlinks a plural form of an existing asset", "description": "Reverts an asset from being a plural form to being a singular asset on its own.\n\nThis action does **not** delete any assets.", "operationId": "unlinkPlural", "parameters": [ { "$ref": "#/components/parameters/uri_asset" }, { "name": "pid", "in": "path", "description": "ID of asset to unlink", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/asset_404" } } } }, "/api/assets": { "get": { "tags": [ "assets" ], "summary": "List all project assets", "description": "Returns an array containing all translatable items (assets) in your project.", "operationId": "getAssets", "parameters": [ { "$ref": "#/components/parameters/tag_filter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } }, "401": { "$ref": "#/components/responses/error_401" } } }, "post": { "tags": [ "assets" ], "summary": "Add a new translatable asset", "description": "Adds a new asset to the currently authenticated project. When created successfully the response will be 201 (created).\n\nSpecifying {text} also creates an initial source language translation (unless you also specify default=untranslated).", "operationId": "createAsset", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "properties": { "id": { "description": "Unique asset ID up to 999 bytes (leave blank to auto-generate)", "type": "string", "maxLength": 999 }, "text": { "description": "Initial source language translation (required if {id} is empty)", "type": "string" }, "type": { "description": "Content type for all translations of the new asset", "type": "string", "default": "text", "enum": [ "text", "html", "xml" ] }, "context": { "description": "Optional context descriptor", "type": "string" }, "notes": { "description": "Optional notes for translators", "type": "string" }, "default": { "description": "Status of the source language translation specified in {text}", "type": "string", "default": "translated" } }, "type": "object" } } } }, "responses": { "201": { "description": "Asset created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" } } } }, "/api/auth/verify": { "get": { "tags": [ "auth" ], "summary": "Verify an API project key", "description": "Loco API keys authenticate your user account for accessing a specific project. This endpoint verifies an API key and returns the authenticated user, account and project.\n\nIf you want to verify whether the key has write access, just send this endpoint a POST request instead. A read-only key will give 403 for any POST request.", "operationId": "authVerify", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credentials" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" } } } }, "/api/export/template.{ext}": { "get": { "tags": [ "export" ], "summary": "Export a template containing only source keys", "description": "This is different to exporting just your source language translations, because it only exports the left hand side of each mapping.", "operationId": "exportTemplate", "parameters": [ { "$ref": "#/components/parameters/export_ext" }, { "$ref": "#/components/parameters/export_format" }, { "$ref": "#/components/parameters/tag_filter" }, { "$ref": "#/components/parameters/export_index" }, { "$ref": "#/components/parameters/export_source" }, { "$ref": "#/components/parameters/export_namespace" }, { "$ref": "#/components/parameters/export_order" }, { "$ref": "#/components/parameters/export_status" }, { "$ref": "#/components/parameters/export_printf" }, { "$ref": "#/components/parameters/export_charset" }, { "$ref": "#/components/parameters/export_breaks" }, { "$ref": "#/components/parameters/export_comments" }, { "$ref": "#/components/parameters/export_expansion" }, { "$ref": "#/components/parameters/export_collisions" }, { "$ref": "#/components/parameters/export_folding_deprecated" } ], "responses": { "200": { "description": "Exported file content", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/error_401" } } } }, "/api/export/all.{ext}": { "get": { "tags": [ "export" ], "summary": "Export all translations in all languages", "description": "Note that not all formats support multiple locales in the same file. See /api/export/archive for exporting separate files, and /api/export/locale for exporting one language at a time.", "operationId": "exportAll", "parameters": [ { "name": "ext", "in": "path", "description": "Target file type specified as a file extension", "required": true, "schema": { "type": "string", "default": "json", "enum": [ "json", "csv", "html", "sql", "tmx", "xlf", "yml" ] } }, { "name": "format", "in": "query", "description": "More specific format of multi-locale file type. e.g. rails applies to yml", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/tag_filter" }, { "$ref": "#/components/parameters/export_index" }, { "$ref": "#/components/parameters/export_source" }, { "$ref": "#/components/parameters/export_fallback" }, { "$ref": "#/components/parameters/export_order" }, { "$ref": "#/components/parameters/export_status" }, { "$ref": "#/components/parameters/export_printf" }, { "$ref": "#/components/parameters/export_charset" }, { "$ref": "#/components/parameters/export_breaks" }, { "$ref": "#/components/parameters/export_comments" }, { "$ref": "#/components/parameters/export_expansion" }, { "$ref": "#/components/parameters/export_collisions" }, { "$ref": "#/components/parameters/export_folding_deprecated" } ], "responses": { "200": { "description": "Exported file content", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/error_401" } } } }, "/api/export/locale/{locale}.{ext}": { "get": { "tags": [ "export" ], "summary": "Export a single locale", "description": "Various export file types are supported with format variations for some types.", "operationId": "exportLocale", "parameters": [ { "$ref": "#/components/parameters/export_locale" }, { "$ref": "#/components/parameters/export_ext" }, { "$ref": "#/components/parameters/export_format" }, { "$ref": "#/components/parameters/tag_filter" }, { "$ref": "#/components/parameters/export_index" }, { "$ref": "#/components/parameters/export_source" }, { "$ref": "#/components/parameters/export_namespace" }, { "$ref": "#/components/parameters/export_fallback" }, { "$ref": "#/components/parameters/export_order" }, { "$ref": "#/components/parameters/export_status" }, { "$ref": "#/components/parameters/export_printf" }, { "$ref": "#/components/parameters/export_charset" }, { "$ref": "#/components/parameters/export_breaks" }, { "$ref": "#/components/parameters/export_comments" }, { "$ref": "#/components/parameters/export_expansion" }, { "$ref": "#/components/parameters/export_collisions" }, { "$ref": "#/components/parameters/export_folding_deprecated" } ], "responses": { "200": { "description": "Exported file content", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/error_401" } } } }, "/api/export/archive/{ext}.zip": { "get": { "tags": [ "export" ], "summary": "Export all locales to a zip archive", "description": "Export all translations from your project to an archive of individual locale files. You can also specify .tar instead of .zip.\n\nIf you're exporting to a format that supports multiple locales per file, you can use the /export/all method instead.", "operationId": "exportArchive", "parameters": [ { "$ref": "#/components/parameters/export_ext" }, { "$ref": "#/components/parameters/export_format" }, { "$ref": "#/components/parameters/tag_filter" }, { "$ref": "#/components/parameters/export_index" }, { "$ref": "#/components/parameters/export_source" }, { "$ref": "#/components/parameters/export_namespace" }, { "$ref": "#/components/parameters/export_fallback" }, { "$ref": "#/components/parameters/export_order" }, { "$ref": "#/components/parameters/export_status" }, { "$ref": "#/components/parameters/export_path" }, { "$ref": "#/components/parameters/export_printf" }, { "$ref": "#/components/parameters/export_charset" }, { "$ref": "#/components/parameters/export_breaks" }, { "$ref": "#/components/parameters/export_comments" }, { "$ref": "#/components/parameters/export_expansion" }, { "$ref": "#/components/parameters/export_collisions" }, { "$ref": "#/components/parameters/export_folding_deprecated" } ], "responses": { "200": { "description": "Zip archive of exported files", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/error_401" } } } }, "/api/import/{ext}": { "post": { "tags": [ "import" ], "summary": "Import assets and translations from a language pack file", "description": "The import API loads translations from various language pack formats into the currently authenticated project.\n\nTake note of how the index and locale parameters are used to describe how your file will be imported. By leaving these fields empty Loco will try to guess your intentions, but it's advisable to specify all parameters if in any doubt.\n\nIt's recommended that you set async=1 for large files. This will cause the import to run in the background. When running asynchronously you will receive a 201 code (instead of 200) and the Location header will contain a URI for checking progress.\n\nWhen running synchronously the response object will include the state of each locale affected by the import.\n\nSee Import settings for full details on all these options.", "operationId": "import", "parameters": [ { "name": "ext", "in": "path", "description": "File extension for the type of file data you're importing", "required": true, "schema": { "type": "string", "enum": [ "arb", "bplist", "csv", "ini", "json", "mo", "php", "plist", "po", "pot", "properties", "res", "resx", "strings", "tmx", "ts", "txt", "xlf", "xml", "yml" ] } }, { "name": "index", "in": "query", "description": "Specify whether translations in your file are indexed by generic IDs or human-readable source text", "required": false, "schema": { "type": "string", "enum": [ "id", "text" ] } }, { "name": "locale", "in": "query", "description": "Specify target locale if importing translations", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Hint for generic file types (like JSON) that don't declare their schema. Reciprocal to the export parameter of the same name", "required": false, "schema": { "type": "string" } }, { "name": "async", "in": "query", "description": "Specify that import should be done asynchronously (recommended for large files)", "required": false, "schema": { "type": "boolean" } }, { "name": "path", "in": "query", "description": "Specify original file path for source code references (excluding line number)", "required": false, "schema": { "type": "string" } }, { "name": "ignore-new", "in": "query", "description": "Specify that new assets will NOT be added to the project", "required": false, "schema": { "type": "boolean" } }, { "name": "ignore-existing", "in": "query", "description": "Specify that existing assets encountered in the file will NOT be updated", "required": false, "schema": { "type": "boolean" } }, { "name": "ignore-blank", "in": "query", "description": "Specify that blank translations should NOT be imported", "required": false, "schema": { "type": "boolean" } }, { "name": "no-comments", "in": "query", "description": "Specify that comment/notes fields in the file should NOT be imported", "required": false, "schema": { "type": "boolean" } }, { "name": "tag-new", "in": "query", "description": "Tag any NEW assets added during the import with the given tags (comma separated)", "required": false, "schema": { "type": "string" } }, { "name": "tag-all", "in": "query", "description": "Tag ALL assets in the file with the given tags (comma separated)", "required": false, "schema": { "type": "string" } }, { "name": "untag-all", "in": "query", "description": "Remove existing tags from any assets matched in the imported file (comma separated)", "required": false, "schema": { "type": "string" } }, { "name": "tag-updated", "in": "query", "description": "Tag existing assets that are MODIFIED by this import", "required": false, "schema": { "type": "string" } }, { "name": "untag-updated", "in": "query", "description": "Remove existing tags from assets that are MODIFIED during import", "required": false, "schema": { "type": "string" } }, { "name": "tag-absent", "in": "query", "description": "Tag existing assets in the project that are NOT found in the imported file", "required": false, "schema": { "type": "string" } }, { "name": "untag-absent", "in": "query", "description": "Remove existing tags from assets NOT found in the imported file", "required": false, "schema": { "type": "string" } }, { "name": "delete-absent", "in": "query", "description": "Permanently DELETES project assets NOT found in the file (use with extreme caution)", "required": false, "schema": { "type": "boolean" } }, { "name": "flag-new", "in": "query", "description": "Set this flag on any NEW translations imported into the current locale", "required": false, "schema": { "type": "string" } }, { "name": "flag-updated", "in": "query", "description": "Set this flag on any translations MODIFIED during import to the current locale", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "description": "Raw source of file being imported", "type": "string", "format": "binary", "default": "" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" } } } }, "201": { "description": "Asynchronous import job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" } } } }, "422": { "description": "Empty or invalid source data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" } } } }, "/api/import/progress/{id}": { "get": { "tags": [ "import" ], "summary": "Check the progress of an asynchronous import", "description": "If you specified async=1 in your original import API request, you can check on its progress with this endpoint.\n\nThe full URL including job identifier will have been provided in the Location header of your original import response.", "operationId": "importProgress", "parameters": [ { "name": "id", "in": "path", "description": "Job identifier from original import action", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncProgress" } } } }, "422": { "description": "Empty job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" } } } }, "/api/locales/{locale}": { "get": { "tags": [ "locales" ], "summary": "Get a project locale", "description": "Gets a single locale in currently authenticated project", "operationId": "getLocale", "parameters": [ { "$ref": "#/components/parameters/uri_locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Locale" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/locale_404" } } }, "delete": { "tags": [ "locales" ], "summary": "Delete a project locale", "description": "Delete a locale from currently authenticated project.\n\n**Warning**: This will permanently delete any translations made in the specified locale across your project.\n\nNote that you cannot delete your source locale.", "operationId": "deleteLocale", "parameters": [ { "$ref": "#/components/parameters/uri_locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/locale_404" } } }, "patch": { "tags": [ "locales" ], "summary": "Modify a project locale", "description": "Modifies the properties of a locale in the currently authenticated project.\n\nThe full, modified locale object is returned.", "operationId": "patchLocale", "parameters": [ { "$ref": "#/components/parameters/uri_locale" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Partial locale data to update", "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Locale" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/locale_404" } } } }, "/api/locales": { "get": { "tags": [ "locales" ], "summary": "List all locales in your project", "description": "Lists all locales in currently authenticated project. Your source language will always be the first in the list", "operationId": "getLocales", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Locale" } } } } }, "401": { "$ref": "#/components/responses/error_401" } } }, "post": { "tags": [ "locales" ], "summary": "Add a new project locale", "description": "Adds a new locale to the currently authenticated project.\n\nIf the locale is created successfully the response will be 201 (created).\n\nIf the locale already exists the response will be 409 (conflict).", "operationId": "createLocale", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "code" ], "properties": { "code": { "description": "Short code, or language tag for new locale", "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Locale created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Locale" } } } }, "409": { "description": "Locale already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" } } } }, "/api/locales/{locale}/progress": { "get": { "tags": [ "locales" ], "summary": "Get more detailed translation progress for a project locale", "description": "Response model is dynamic according to the status/flags available in your project.\n\nStatus keys such as 'translated' or 'fuzzy' are only included when there are assets with that status and in future may be user-defined.", "operationId": "getLocaleProgress", "parameters": [ { "$ref": "#/components/parameters/uri_locale" }, { "$ref": "#/components/parameters/tag_filter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/error_401" } } } }, "/api/locales/{locale}/errors": { "get": { "tags": [ "locales" ], "summary": "Get validation errors for a project locale", "description": "Checks all translations in the given locale for the validation errors that appear in the user interface.", "operationId": "getLocaleErrors", "parameters": [ { "$ref": "#/components/parameters/uri_locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TranslationError" } } } } }, "401": { "$ref": "#/components/responses/error_401" } } } }, "/api/tags": { "get": { "tags": [ "tags" ], "summary": "Get project tags", "description": "Lists all tags in currently authenticated project", "operationId": "getTags", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "$ref": "#/components/responses/error_401" } } }, "post": { "tags": [ "tags" ], "summary": "Create a new tag", "description": "Adds a new tag to the currently authenticated project", "operationId": "createTag", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Name of new tag", "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" } } } }, "/api/tags/{tag}.json": { "post": { "tags": [ "tags" ], "summary": "Add multiple assets to an existing tag", "description": "Tag multiple assets at once by posting their unique IDs to the tag's resource", "operationId": "tagAssets", "parameters": [ { "$ref": "#/components/parameters/uri_tag" } ], "requestBody": { "required": true, "content": { "text/plain": { "schema": { "description": "Comma separated list of unique asset IDs", "type": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/tag_404" } } }, "delete": { "tags": [ "tags" ], "summary": "Delete an existing tag", "description": "Deletes an existing tag in the currently authenticated project", "operationId": "deleteTag", "parameters": [ { "$ref": "#/components/parameters/uri_tag" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/tag_404" } } }, "patch": { "tags": [ "tags" ], "summary": "Modify a single tag", "description": "Renames an existing tag in the currently authenticated project", "operationId": "patchTag", "parameters": [ { "$ref": "#/components/parameters/uri_tag" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "New tag name", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/tag_404" } } } }, "/api/translations/{id}/{locale}": { "get": { "tags": [ "translations" ], "summary": "Get a single translation", "description": "Gets a single translation in currently authenticated project.\n\nTranslations implicitly exist as long as the asset and locale are in your project.\n\nTranslations marked as complete have the translated field set to true.", "operationId": "getTranslation", "parameters": [ { "$ref": "#/components/parameters/uri_asset" }, { "$ref": "#/components/parameters/uri_locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Translation" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/error_404" } } }, "post": { "tags": [ "translations" ], "summary": "Add a new translation in a given locale", "description": "Translates a single asset in a single locale in the currently authenticated project.\n\nIf the asset is already translated, a new revision will be added and the revision field incremented.\n\nIf the asset is untranslated the locale must have already been added to the project.", "operationId": "translate", "parameters": [ { "$ref": "#/components/parameters/uri_asset" }, { "$ref": "#/components/parameters/uri_locale" } ], "requestBody": { "required": false, "content": { "text/plain": { "schema": { "description": "Raw value of new translation. Sending empty marks as 'untranslated'", "type": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Translation" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/asset_404" } } }, "delete": { "tags": [ "translations" ], "summary": "Erase translation data in a single locale", "description": "Erases translation data of a localized asset in the currently authenticated project.\n\n**Warning**: Erasing is not the same as setting an empty translation. This operation clears the asset's translation history and user comments for the given locale.", "operationId": "untranslate", "parameters": [ { "$ref": "#/components/parameters/uri_asset" }, { "$ref": "#/components/parameters/uri_locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/error_404" } } } }, "/api/translations/{id}.json": { "get": { "tags": [ "translations" ], "summary": "Get all translations of an asset", "description": "Gets all translations of an asset across the currently authenticated project's locales.\n\nLocales not yet translated are included, but their translated field will be set to false.", "operationId": "getTranslations", "parameters": [ { "$ref": "#/components/parameters/uri_asset" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Translation" } } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/asset_404" } } } }, "/api/translations/{id}/{locale}/flag": { "post": { "tags": [ "translations" ], "summary": "Flag a translation in a given locale", "description": "Flag a single translation or set its status in a given locale.\n\nThe flag parameter can be any flag (e.g. fuzzy) a status (e.g. translated) or a redundant state (e.g. blank translation). See translation states.", "operationId": "flagTranslation", "parameters": [ { "$ref": "#/components/parameters/uri_asset" }, { "$ref": "#/components/parameters/uri_locale" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "flag" ], "properties": { "flag": { "description": "Flag or status to set, e.g. "fuzzy"", "type": "string", "default": "fuzzy" } }, "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/asset_404" } } }, "delete": { "tags": [ "translations" ], "summary": "Clear flag from a translation", "description": "Removes current flag from a translation marked as incomplete or in error.\n\nIt's not necessary to specify which flag to remove, because there can be only one.", "operationId": "unflagTranslation", "parameters": [ { "$ref": "#/components/parameters/uri_asset" }, { "$ref": "#/components/parameters/uri_locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/asset_404" } } } }, "/api/translations/{id}/{locale}/revisions": { "get": { "tags": [ "translations" ], "summary": "Get previous revisions of a translation", "description": "Returns the array containing all previous translations of the given asset in the given locale.", "operationId": "getRevisions", "parameters": [ { "$ref": "#/components/parameters/uri_asset" }, { "$ref": "#/components/parameters/uri_locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } }, "401": { "$ref": "#/components/responses/error_401" }, "404": { "$ref": "#/components/responses/asset_404" } } } } }, "components": { "schemas": { "Asset": { "required": [ "id", "type", "context", "notes", "modified", "tags", "plurals" ], "properties": { "id": { "description": "Unique asset identifier", "type": "string" }, "type": { "description": "Content type for translations", "type": "string", "default": "text", "enum": [ "text", "html", "xml" ] }, "context": { "description": "Optional context descriptor", "type": "string" }, "notes": { "description": "Optional notes for translators", "type": "string" }, "printf": { "description": "String formatting style. See string formatting", "type": "string" }, "created": { "description": "Time first added in UTC", "type": "string", "format": "date-time" }, "modified": { "description": "Time last modified in UTC", "type": "string", "format": "date-time" }, "plurals": { "description": "Number of associated plural forms", "type": "integer" }, "tags": { "description": "Array of terms asset is tagged with", "type": "array", "items": { "type": "string" } }, "aliases": { "description": "Hash of additional asset identifiers, e.g. {"android":"myId"}", "type": "object" }, "progress": { "$ref": "#/components/schemas/AssetProgress" } }, "type": "object" }, "AssetProgress": { "description": "Statistical summary of translation progress for an individual locale", "required": [ "translated", "untranslated", "flagged" ], "properties": { "translated": { "description": "Number of locales for which a translation exists (including those flagged)", "type": "integer" }, "untranslated": { "description": "Number of locales that do not yet have a translation of this asset", "type": "integer" }, "flagged": { "description": "Number of locales whose translations are flagged as requiring attention", "type": "integer" } }, "type": "object" }, "AsyncProgress": { "description": "Job progress for checking asynchronous operations", "required": [ "progress" ], "properties": { "progress": { "description": "Percentage progress through asynchronous operation", "type": "integer", "maximum": 100, "minimum": 0 }, "success": { "description": "Message populated after successful completion", "type": "string" }, "error": { "description": "Description of any error that prevented the operation from finishing", "type": "string" } }, "type": "object" }, "Credentials": { "required": [ "user", "group", "project" ], "properties": { "user": { "$ref": "#/components/schemas/User" }, "group": { "$ref": "#/components/schemas/Group" }, "project": { "$ref": "#/components/schemas/Project" } }, "type": "object" }, "Error": { "required": [ "status", "error" ], "properties": { "status": { "description": "HTTP status code", "type": "integer", "default": 500 }, "error": { "description": "Description of error", "type": "string" } }, "type": "object" }, "Group": { "properties": { "id": { "description": "Loco account id", "type": "integer" }, "name": { "description": "Loco account name", "type": "string" }, "url": { "description": "Dashboard URL", "type": "string" } }, "type": "object" }, "ImportResult": { "required": [ "status", "message", "locales" ], "properties": { "status": { "description": "Whether import was synchronous (200) or asynchronous (201)", "type": "integer", "default": 200, "enum": [ 200, 201 ] }, "message": { "description": "Summary of import result", "type": "string" }, "locales": { "description": "Locales identified during import with their progress statistics", "type": "array", "items": { "$ref": "#/components/schemas/Locale" } } }, "type": "object" }, "Locale": { "required": [ "code", "name", "native", "plurals", "progress" ], "properties": { "code": { "description": "Locale short code, or language tag", "type": "string" }, "name": { "description": "Friendly display name", "type": "string" }, "source": { "description": "Whether the default/source locale of the project", "type": "boolean" }, "native": { "description": "DEPRECATED: alias of "source" will be removed in future", "type": "boolean" }, "created": { "description": "Time first added in UTC", "type": "string", "format": "date-time" }, "modified": { "description": "Time last modified in UTC", "type": "string", "format": "date-time" }, "plurals": { "$ref": "#/components/schemas/PluralRules" }, "progress": { "$ref": "#/components/schemas/LocaleProgress" } }, "type": "object" }, "LocaleProgress": { "description": "Statistical summary of translation progress for an individual locale", "required": [ "translated", "untranslated", "flagged" ], "properties": { "translated": { "description": "Number of assets for which a translation exists (including those flagged)", "type": "integer" }, "untranslated": { "description": "Number of assets that are not yet translated to this language", "type": "integer" }, "flagged": { "description": "Number of translations that are flagged as requiring attention", "type": "integer" }, "words": { "description": "Approximate word count for translated texts in this language", "type": "integer" } }, "type": "object" }, "PingResponse": { "required": [ "version", "build" ], "properties": { "version": { "description": "Current API version", "type": "string" }, "build": { "description": "Current build identifer", "type": "string" } }, "type": "object" }, "PluralRules": { "required": [ "length", "equation", "forms" ], "properties": { "length": { "description": "Number of forms including singular", "type": "integer", "default": 2, "maximum": 6, "minimum": 1 }, "equation": { "description": "Equation for calculating offset in forms. The formula takes a multiplier (n) to yield a plural form offset. ( 0 <= offset < length ).", "type": "string", "default": "n != 1" }, "forms": { "description": "Plural form names. See Unicode tr35.", "type": "array", "items": { "type": "string", "enum": [ "zero", "one", "two", "few", "many", "other" ] } } }, "type": "object" }, "PluralTranslation": { "description": "Base class containing subset of the fields of LocoApiTranslationModel\nDoesn't need $plurals or $locale", "required": [ "id", "translated", "flagged", "translation", "revision", "comments" ], "properties": { "id": { "description": "Asset ID", "type": "string" }, "status": { "description": "Status of translation as string compatible with export status parameter", "type": "string" }, "flagged": { "description": "Whether translation is flagged as requiring attention", "type": "boolean", "default": false }, "translated": { "description": "Whether asset is translated and contributing to project completion", "type": "boolean", "default": false }, "translation": { "description": "Translated text in specified locale", "type": "string" }, "revision": { "description": "Number of edits made, zero if never translated", "type": "integer", "default": 0 }, "comments": { "description": "Number of comments available", "type": "integer" }, "modified": { "description": "Time last modified in UTC, null if translation doesn't exist", "type": "string", "format": "date-time", "nullable": true }, "author": { "oneOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true, "description": "Team member that edited this most recent revision" }, "flagger": { "oneOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true, "description": "Team member that flagged the translation, if flagged is set" } }, "type": "object" }, "Project": { "properties": { "id": { "description": "Project id", "type": "integer" }, "name": { "description": "Project name", "type": "string" }, "url": { "description": "Project dashboard URL", "type": "string" }, "created": { "description": "Time first added in UTC", "type": "string", "format": "date-time" }, "modified": { "description": "Time last modified in UTC", "type": "string", "format": "date-time" } }, "type": "object" }, "Revision": { "required": [ "id", "translated", "flagged", "translation", "revision" ], "properties": { "status": { "description": "Status of translation as string compatible with export status parameter", "type": "string" }, "flagged": { "description": "Whether translation is flagged as requiring attention", "type": "boolean", "default": false }, "translated": { "description": "Whether the translation exists (even if flagged)", "type": "boolean", "default": false }, "translation": { "description": "Translated text in specified locale", "type": "string" }, "revision": { "description": "Number of edits made, zero if never translated", "type": "integer", "default": 0 }, "modified": { "description": "Time last modified in UTC, null if translation doesn't exist", "type": "string", "format": "date-time", "nullable": true }, "author": { "oneOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true, "description": "Team member that edited this most recent revision" }, "flagger": { "oneOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true, "description": "Team member that flagged the translation, if flagged is set" } }, "type": "object" }, "Success": { "required": [ "status", "message" ], "properties": { "status": { "description": "HTTP status 2xx code", "type": "integer", "default": 200 }, "message": { "description": "Descriptive success message", "type": "string" } }, "type": "object" }, "TranslationError": { "required": [ "id", "status", "source", "errors" ], "properties": { "id": { "description": "Unique asset ID for current translation", "type": "string" }, "status": { "description": "Status of translation as string compatible with export status parameter", "type": "string" }, "source": { "description": "Source text in default project locale", "type": "string" }, "target": { "description": "Translated text in current target locale (unless locale is source)", "type": "string", "nullable": true }, "errors": { "description": "Validation errors as simple message strings", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "Translation": { "required": [ "id", "translated", "flagged", "translation", "revision", "comments", "locale", "plurals" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/PluralTranslation" }, { "properties": { "id": { "description": "Unique asset ID for which this is a translation", "type": "string" }, "status": { "description": "Status of translation as string compatible with export status parameter", "type": "string" }, "flagged": { "description": "Whether translation is flagged as requiring attention", "type": "boolean", "default": false }, "translated": { "description": "Whether the translation exists (even if flagged)", "type": "boolean", "default": false }, "translation": { "description": "Translated text in specified locale", "type": "string" }, "revision": { "description": "Number of edits made, zero if never translated", "type": "integer", "default": 0 }, "comments": { "description": "Number of comments available", "type": "integer" }, "modified": { "description": "Time last modified in UTC, null if translation doesn't exist", "type": "string", "format": "date-time", "nullable": true }, "author": { "oneOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true, "description": "Team member that edited this most recent revision" }, "flagger": { "oneOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true, "description": "Team member that flagged the translation, if flagged is set" }, "locale": { "oneOf": [ { "$ref": "#/components/schemas/Locale" } ], "nullable": true, "description": "Locale this is translated to" }, "plurals": { "description": "Plural forms of this translation", "type": "array", "items": { "$ref": "#/components/schemas/PluralTranslation" } } }, "type": "object" } ] }, "User": { "required": [ "id" ], "properties": { "id": { "description": "User id", "type": "integer" }, "name": { "description": "Full user name", "type": "string" }, "email": { "description": "Contact email address if you have permission to see it", "type": "string" } }, "type": "object" } }, "responses": { "error_401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "status": { "description": "OpenAPI 3.x component definitions for the Loco REST API", "type": "integer", "default": 401 } }, "type": "object" } ] } } } }, "error_403": { "description": "Insufficient privileges", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "status": { "type": "integer", "default": 403 } }, "type": "object" } ] } } } }, "error_404": { "description": "One or more referenced resources not found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "status": { "type": "integer", "default": 404 } }, "type": "object" } ] } } } }, "locale_404": { "description": "Locale not in project", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "status": { "type": "integer", "default": 404 } }, "type": "object" } ] } } } }, "asset_404": { "description": "Asset not in project", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "status": { "type": "integer", "default": 404 } }, "type": "object" } ] } } } }, "translation_404": { "description": "Asset not translated in this locale", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "status": { "type": "integer", "default": 404 } }, "type": "object" } ] } } } }, "tag_404": { "description": "Tag not in project", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "status": { "type": "integer", "default": 404 } }, "type": "object" } ] } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": { "uri_locale": { "name": "locale", "in": "path", "description": "Locale short code, or language tag", "required": true, "schema": { "type": "string" } }, "uri_asset": { "name": "id", "in": "path", "description": "Asset ID", "required": true, "schema": { "type": "string" } }, "tag_filter": { "name": "filter", "in": "query", "description": "Filter assets by comma-separated tag names. Match any tag with `*` and negate tags by prefixing with `!`", "required": false, "schema": { "type": "string" } }, "uri_tag": { "name": "tag", "in": "path", "description": "Name of a single asset tag.", "required": false, "schema": { "type": "string" } }, "export_ext": { "name": "ext", "in": "path", "description": "Target file type specified as a file extension. See available options.", "required": true, "schema": { "type": "string", "default": "json" } }, "export_format": { "name": "format", "in": "query", "description": "More specific format of file type. e.g. symfony applies to php, xlf & yml", "required": false, "schema": { "type": "string" } }, "export_locale": { "name": "locale", "in": "path", "description": "Locale to export, specified as short code or language tag. e.g. `en` or `en_GB`", "required": true, "schema": { "type": "string" } }, "export_fallback": { "name": "fallback", "in": "query", "description": "Fallback locale for untranslated assets, specified as short code. e.g. `en` or `en_GB`", "required": false, "schema": { "type": "string" } }, "export_index": { "name": "index", "in": "query", "description": "Override default lookup key for the file format: "id", "text" or a custom alias", "required": false, "schema": { "type": "string" } }, "export_source": { "name": "source", "in": "query", "description": "Specify alternative source locale instead of project default", "required": false, "schema": { "type": "string" } }, "export_namespace": { "name": "namespace", "in": "query", "description": "Override the project name for some language packs that use it as a key prefix", "required": false, "schema": { "type": "string" } }, "export_status": { "name": "status", "in": "query", "description": "Export translations with a specific status or flag. Negate values by prefixing with `!`. e.g. "translated", or "!fuzzy".", "required": false, "schema": { "type": "string" } }, "export_order": { "name": "order", "in": "query", "description": "Export translations according to asset order", "required": false, "schema": { "type": "string", "enum": [ "created", "id" ] } }, "export_path": { "name": "path", "in": "query", "description": "Custom pattern for file paths. See syntax", "required": false, "schema": { "type": "string" } }, "export_printf": { "name": "printf", "in": "query", "description": "Force alternative "printf" style. See string formatting", "required": false, "schema": { "type": "string", "enum": [ "php", "java", "objc", "icu", "python" ] } }, "export_collisions": { "name": "collisions", "in": "query", "description": "Override the default strategy for handling conflicting keys. See key collisions.", "required": false, "schema": { "type": "string", "enum": [ "overwrite", "ignore", "fail", "auto", "legacy" ] } }, "export_expansion": { "name": "no-expand", "in": "query", "description": "Protect dot notation in keys so that `foo.bar` is not expanded to an object.", "required": false, "schema": { "type": "boolean" } }, "export_folding_deprecated": { "name": "no-folding", "in": "query", "description": "DEPRECATED: alias of `no-expand` for backward compatibility.", "required": false, "schema": { "type": "boolean" } }, "export_comments": { "name": "no-comments", "in": "query", "description": "Disable rendering of redundant inline comments including the Loco banner.", "required": false, "schema": { "type": "boolean" } }, "export_charset": { "name": "charset", "in": "query", "description": "Specify preferred character encoding. Alternative to `Accept-Charset` header but accepts a single value which must be valid.", "required": false, "schema": { "type": "string" } }, "export_breaks": { "name": "breaks", "in": "query", "description": "Force platform-specific line-endings. Default is Unix (LF) breaks.", "required": false, "schema": { "type": "string", "enum": [ "Unix", "DOS", "Mac" ] } } }, "securitySchemes": { "ApiKeyQuery": { "type": "apiKey", "description": "API key as query parameter.", "name": "key", "in": "query" }, "ApiKeyHeader": { "type": "apiKey", "description": "API key as Authorization header; prefixed as \"Loco YOUR_KEY\".", "name": "Authorization", "in": "header" } } }, "security": [ { "ApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "tags": [ { "name": "assets", "description": "Manage translatable assets" }, { "name": "auth", "description": "Authentication utilities" }, { "name": "export", "description": "Export translations to language pack formats.\n\nSee supported export formats and more detail on the available options." }, { "name": "import", "description": "Import translations from language packs" }, { "name": "locales", "description": "Manage project locales" }, { "name": "tags", "description": "Manage project tags" }, { "name": "translations", "description": "Manage and update individual translations" } ] }