API

File API

Create, show, update, delete and zip language files with the WebTranslateIt File API, with curl, JavaScript, Python, Ruby and PHP examples. 9 min read

The File API is composed of 6 endpoints:

Show File — serves a language file
Update File — update a language file
Create File — create a master language file
Delete File — delete a language file, as well as its attached target files and translations
Zip File — Serves all files in a project as a zip archive
Refresh Files — re-fetch every file the project pulls from a URL

Show File

This endpoint is accessible by both read-write and read-only Project API keys and serves your language file in the same format/extension than the one you uploaded.

/api/projects/:project_token/files/:master_project_file_id/locales/:locale_code [GET]

Example: https://webtranslateit.com/api/projects/98e71ee45042066f1053ed900b4e8f4ec1f98451/files/1943/locales/en

An alternate endpoint allows to retrieve a file by path:

/api/projects/:project_token/files/...?file_path=path/to/file.po [GET]

Example: https://webtranslateit.com/api/projects/98e71ee45042066f1053ed900b4e8f4ec1f98451/files/…?file_path=config/locales/app/fr.yml

In order to improve your app’s performance you can use conditional requests to interrogate this endpoint. If you add to your headers a If-Modified-Since (UTC Timezone, rfc2822 format) set to the date of last modification of your file, WebTranslateIt will either respond a 304 Not Modified HTTP code with no body if your version of the file is fresh, or a 200 OK HTTP code if your version of the language file is stale.

GET/api/projects/:project_token/files/:master_project_file_id/locales/:locale_code

curl -o fr.yml \
  "https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr"

import { writeFile } from 'node:fs/promises'

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr'
)
await writeFile('fr.yml', await response.text())

import requests

response = requests.get(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr"
)
with open("fr.yml", "wb") as target:
    target.write(response.content)

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr')
File.write('fr.yml', Net::HTTP.get(uri))

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
file_put_contents('fr.yml', curl_exec($ch));
curl_close($ch);

To fetch the file only when it changed, send the timestamp you last downloaded it:

bash

curl -o fr.yml \
  -H "If-Modified-Since: Tue, 15 Nov 2022 12:45:26 GMT" \
  "https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr"

Update File

This endpoint is only accessible by the read-write Project API key and is used to update a language file (master or target).

/api/projects/:project_token/files/:master_project_file_id/locales/:locale_code [PATCH]

NEW An alternate endpoint allows to update a file by path:

/api/projects/:project_token/files/...?file_path=path/to/file.po [PATCH]

Parameters:

file: the file itself, encoded in multipart. Each part should have the file name.

Optional parameters

name, the file name,
NEW: rename_others, when the modified file is a master file and the optional name parameter is passed, set the rename_others option to true to rename the target files as well.
merge=true, to disable overwriting strings (default is false),
ignore_missing=true, to disable obsoleting strings (default is false),
minor_changes=true, to prevent a translation change in source language to flag target translations as “to verify”,
label, the label to assign to all changes made during this update.

If everything goes well, the server should respond with 202 Accepted in the response headers. Please note that the file is processed by a background job on WebTranslateIt’s server, so the update might not immediately be available. You can check the file’s status in the File Manager.

Error messages

Locale not found: the locale specified wasn’t found on your project.
File not found: couldn’t find a file with this ID.
File attachment not found: a file wasn’t multipart-posted with this request.
Pushing a target hash-based file (.txt, .html, .textile or Markdown) is not allowed.: Some file formats don’t allow pushing updates to target files.
File is being processed at the moment: this file is currently being imported. You can try updating that file later when imported. Why?
File is already queued for import: this file is already in queue for import. It will be imported later. You can try updating that file later when imported. Why?
Master File is being processed at the moment: the master file of this file is currently being imported. You can try updating that file later when its master file is imported. Why?
Master File is queued for import: the master file of this file is in queue for import. It will be imported later. You can try updating that file later when its master file is imported. Why?

Examples

The file is sent as multipart form data, so every example below posts the file itself rather than a JSON body.

PATCH/api/projects/:project_token/files/:master_project_file_id/locales/:locale_code

curl -X PATCH "https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr" \
  -F "file=@config/locales/fr.yml" \
  -F "name=config/locales/fr.yml" \
  -F "merge=true"

import { openAsBlob } from 'node:fs'

const form = new FormData()
form.append('file', await openAsBlob('config/locales/fr.yml'), 'fr.yml')
form.append('name', 'config/locales/fr.yml')
form.append('merge', 'true')

await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr',
  { method: 'PATCH', body: form }
)

import requests

with open("config/locales/fr.yml", "rb") as source:
    requests.patch(
        "https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr",
        files={"file": source},
        data={"name": "config/locales/fr.yml", "merge": "true"},
    )

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr')
File.open('config/locales/fr.yml') do |file|
  request = Net::HTTP::Patch.new(uri)
  request.set_form([
    ['file', file],
    ['name', 'config/locales/fr.yml'],
    ['merge', 'true']
  ], 'multipart/form-data')
  Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
end

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943/locales/fr');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'file' => new CURLFile('config/locales/fr.yml'),
    'name' => 'config/locales/fr.yml',
    'merge' => 'true',
]);
curl_exec($ch);
curl_close($ch);

Create File

This endpoint is only accessible by the read-write Project API key and is used to create a new master language file.

/api/projects/:project_token/files [POST]

Parameters

file: the file itself
name: the file name (optional)

If everything goes well, the server should respond with 201 Created in the response headers, the master file ID in the response body. Please note that the file is processed by a background job on WebTranslateIt’s server, so the update might not immediately be available. You can check the file’s status in the File Manager.

POST/api/projects/:project_token/files

curl -X POST "https://webtranslateit.com/api/projects/PROJECT_TOKEN/files" \
  -F "file=@config/locales/en.yml" \
  -F "name=config/locales/en.yml"

import { openAsBlob } from 'node:fs'

const form = new FormData()
form.append('file', await openAsBlob('config/locales/en.yml'), 'en.yml')
form.append('name', 'config/locales/en.yml')

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/files',
  { method: 'POST', body: form }
)
const masterFileId = await response.text()

import requests

with open("config/locales/en.yml", "rb") as source:
    response = requests.post(
        "https://webtranslateit.com/api/projects/PROJECT_TOKEN/files",
        files={"file": source},
        data={"name": "config/locales/en.yml"},
    )
master_file_id = response.text

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/files')
File.open('config/locales/en.yml') do |file|
  request = Net::HTTP::Post.new(uri)
  request.set_form([['file', file], ['name', 'config/locales/en.yml']], 'multipart/form-data')
  response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
  master_file_id = response.body
end

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/files');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'file' => new CURLFile('config/locales/en.yml'),
    'name' => 'config/locales/en.yml',
]);
$masterFileId = curl_exec($ch);
curl_close($ch);

Delete File

This endpoint is only accessible by the read-write Project API key and is used to delete a master language file.

/api/projects/:project_token/files/:file_id [DELETE]

NEW An alternate endpoint allows to update a file by path:

/api/projects/:project_token/files/...?file_path=path/to/file.po [DELETE]

If everything goes well, the server should respond with 202 Accepted in the response headers. Please note that deleting the master file, target files as well as segments and translations is processed by a background job on WebTranslateIt’s server, so the update might not immediately be available.

DELETE/api/projects/:project_token/files/:file_id

curl -X DELETE "https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943"

await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943',
  { method: 'DELETE' }
)

import requests

requests.delete(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943"
)

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943')
Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(Net::HTTP::Delete.new(uri))
end

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/files/1943');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_exec($ch);
curl_close($ch);

Zip File

This endpoint is accessible by both read-write and read-only Project API keys and is used to download a zip archive containing all files in a project.

/api/projects/:project_token/zip_file [GET]

If everything goes well, the server sends a zip file containing all files in a project.

GET/api/projects/:project_token/zip_file

curl -o translations.zip \
  "https://webtranslateit.com/api/projects/PROJECT_TOKEN/zip_file"

import { writeFile } from 'node:fs/promises'

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/zip_file'
)
await writeFile('translations.zip', Buffer.from(await response.arrayBuffer()))

import requests

response = requests.get(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/zip_file"
)
with open("translations.zip", "wb") as archive:
    archive.write(response.content)

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/zip_file')
File.binwrite('translations.zip', Net::HTTP.get(uri))

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/zip_file');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
file_put_contents('translations.zip', curl_exec($ch));
curl_close($ch);

Download files for a specific locale

If you add the optional parameter ?locale=xx containing a locale code this endpoint will serve all the files for a specific locale for a project as a zip file.

bash

curl -o fr.zip \
  "https://webtranslateit.com/api/projects/PROJECT_TOKEN/zip_file?locale=fr"

Refresh Files

This endpoint is accessible by both read-write and read-only Project API keys.

/api/projects/:project_token/refresh_files [POST]

A file can be added to a project by giving WebTranslateIt the URL to fetch it from, rather than by uploading it. Files added that way are re-fetched periodically, so that changes made at the source find their way into the project on their own.

This endpoint asks WebTranslateIt to re-fetch all of the project’s remote files immediately, instead of waiting for the next scheduled refresh. It is what you call from a build or deploy script when you have just published new source files and want them picked up now.

Files that were uploaded directly are not affected — there is nowhere to re-fetch them from. If no file in the project was added from a URL, this endpoint does nothing.

The server downloads each remote file before responding 200 OK, so a project with many remote files, or one whose source server is slow, will take a while to answer. Allow a generous timeout in your script.

Importing the downloaded files — parsing them and creating or updating segments — then happens in the background. A 200 OK therefore means “fetched”, not “imported”. Poll the Stats API if you need to know when the new segments have actually landed.

POST/api/projects/:project_token/refresh_files

curl -X POST --max-time 300 \
  "https://webtranslateit.com/api/projects/PROJECT_TOKEN/refresh_files"

await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN/refresh_files',
  { method: 'POST', signal: AbortSignal.timeout(300_000) }
)

import requests

requests.post(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN/refresh_files",
    timeout=300,
)

require 'net/http'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/refresh_files')
Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 300) do |http|
  http.request(Net::HTTP::Post.new(uri))
end

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/refresh_files');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 300);
curl_exec($ch);
curl_close($ch);

Documentation

File API

Show File#

Update File#

Parameters:#

Optional parameters#

Error messages#

Examples#

Create File#

Parameters#

Delete File#

Zip File#

Download files for a specific locale#

Refresh Files#