Skip to content

API V1

Resources

Endpoints for the operations that can be performed on the resource files

Resource files are the files of a project: one per language, or one for all languages, depending on the file format. Listing and downloading need the resourcesView permission on the project; uploading and deleting need resourcesManage.

Every operation accepts the query parameter branch, the name of a project branch. Without it, LingoHub uses the default branch; an unknown name returns 422.

List resource files

The list has one entry per file and language. The self link of an entry is the download URL of that file, with path already set.

Parameter Meaning
localeInFileName Which file names carry the language: ALL (default), TARGETS (target languages only) or NONE.
addIso2Slug true adds the parameter iso2_slug with the language code to every download link.

Download a resource file

The response is the file itself. All query parameters are optional; a parameter you omit takes the value of the project’s export settings.

Parameter Meaning
path Path of the file. Needed when the file name alone isn’t unique in the project.
iso2_slug, iso2_code The language to export. Both names mean the same.
source:blankContentHandling, target:blankContentHandling What happens to a text without content in the source language or in a target language: skip leaves it out, keep exports it empty. blank, fallback, use_source and master_locale are older names for keep.
source:filterByStatus, target:filterByStatus Which texts are exported: ALL, TRANSLATED_AND_APPROVED (status Translated or Approved) or APPROVED. TRANSLATED_AND_REVIEWED and REVIEWED are older names for the last two.
htmlEncoding, escapeMode How HTML in a text is written: RAW, ESCAPE or CDATA. Both names mean the same.
encoding Character encoding of the file, for example UTF-8 or ISO-8859-1.
addLocaleInformationToFilename Which file names carry the language: ALL, TARGETS or NONE.
escapeCharacters Whether special characters are escaped. The effect depends on the file format.
exportTargetComments true writes comments into the files of every language, false only into the source language file.
projectType Writes the file in another format: ios.strings, ios.stringsdict, android.string.resources, properties or standard_json.

An invalid value returns 422 for the blank-content, status, encoding and projectType parameters, and 400 for the others.

exportSourceLocale, exportHeader, exportTitle and exportDescription are accepted and have no effect.

The response carries a weak ETag. Send it back as If-None-Match to get 304 Not Modified without a body as long as the file hasn’t changed. If-Modified-Since alone isn’t evaluated.

Upload a resource file

Send the file as the file part of a multipart/form-data request and the other parameters in the query string.

  • Language. LingoHub detects the language from the file name and the path. iso2_slug (or iso2_code) overrides the detection.
  • Import settings. source:createNew, source:updateExisting and source:deactivateMissing decide, for a file of the source language, whether the import creates new keys, updates changed texts and deactivates keys that are missing in the file. The target: parameters do the same for a file of a target language. A parameter you omit takes the value of the project’s import settings.
  • Result. 201 with {"status": "Success"} means that LingoHub accepted the file. The import runs afterwards.
  • File extension. A file whose extension the project type can’t import returns 422 with the code files.invalid_extension.

Uploads without a path

If you upload a file without path and the project already has a file of that name under a path, LingoHub holds the upload back with 406 Not Acceptable, because it can’t tell which file you mean. Send path, or send force=true to upload the file as it is.

Upload a ZIP archive

LingoHub imports every visible file of the archive and detects the languages from the file names and paths. The import settings work as for a single file. An archive without visible files returns 400; an entry with an unsupported extension returns 422.

Delete a resource file

The operation deletes a file in all its languages. fileName, with path if needed, must name the file of the source language; the name of a target language file returns 400.

Errors

Status Meaning
400 A parameter has an invalid value, the archive is empty, or the file to delete isn’t the source language file.
401 The API key is missing or invalid.
403 The key lacks the permission the operation needs.
404 The workspace, the project or the file doesn’t exist.
406 An upload without path was held back; see above.
422 A download parameter has an invalid value (see above), the branch doesn’t exist, or the project type can’t import the file.
500 The import or export failed unexpectedly.

Operations

Operation Request
Upload a resource file ZIP archive POST /v1/{workspaceUrl}/projects/{projectUrl}/resources/zip
List resource files GET /v1/{workspaceUrl}/projects/{projectUrl}/resources
Upload a resource file POST /v1/{workspaceUrl}/projects/{projectUrl}/resources
Download a resource file GET /v1/{workspaceUrl}/projects/{projectUrl}/resources/{fileName}
Delete a resource container DELETE /v1/{workspaceUrl}/projects/{projectUrl}/resources/{fileName}