API V1
Resources
Resources
Section titled “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(oriso2_code) overrides the detection. - Import settings.
source:createNew,source:updateExistingandsource:deactivateMissingdecide, 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. Thetarget: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.
201with{"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
422with the codefiles.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} |