# Resources

LingoHub API V1 · [all operations](https://developers.lingohub.com/reference/v1.md)

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

- [`POST /v1/{workspaceUrl}/projects/{projectUrl}/resources/zip`](https://developers.lingohub.com/reference/v1/operations/v1resourceuploadresourcefilezip.md): Upload a resource file ZIP archive
- [`GET /v1/{workspaceUrl}/projects/{projectUrl}/resources`](https://developers.lingohub.com/reference/v1/operations/v1resourcegetresourceinfolist.md): List resource files
- [`POST /v1/{workspaceUrl}/projects/{projectUrl}/resources`](https://developers.lingohub.com/reference/v1/operations/v1resourceuploadresourcefile.md): Upload a resource file
- [`GET /v1/{workspaceUrl}/projects/{projectUrl}/resources/{fileName}`](https://developers.lingohub.com/reference/v1/operations/v1resourcedownloadresourcefile.md): Download a resource file
- [`DELETE /v1/{workspaceUrl}/projects/{projectUrl}/resources/{fileName}`](https://developers.lingohub.com/reference/v1/operations/v1resourcedeleteresourcecontainer.md): Delete a resource container
