File API
The File API is composed of 5 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
🔗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]
An alternate endpoint allows to retrieve a file by path:
/api/projects/:project_token/files/...?file_path=path/to/file.po [GET]
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.
🔗Implementation Example in Ruby:
require "net/http"
http = Net::HTTP.new("webtranslateit.com", 443)
http.use_ssl = true
request = Net::HTTP::Get("/api/projects/:api_token/files/:file_id/locales/:locale_code")
response = http.request(request)
puts response.body
🔗Implementation Example in PHP:
<?php
$api_key = "sekret";
$file_id = "1234";
$locale_code = "fr";
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/files/" . $file_id . "/locales/" . $locale_code);
$response = curl_exec($ch);
curl_close($ch);
?>
🔗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 optionalnameparameter is passed, set therename_othersoption totrueto 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 taht 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?
🔗Implementation Example in Java:
MultipartPostMethod method = new MultipartPostMethod(url);
File file = new File( "data", "test.txt");
File file2 = new File( "data", "sample.txt");
method.addParameter("test.txt", file);
method.addPart(new FilePart("sample.txt", file2, "text/plain", "ISO-8859-1"));
🔗Implementation Example in Ruby:
require "net/http"
require "net/http/post/multipart" # gem install multipart-post
http = Net::HTTP.new("webtranslateit.com", 443)
http.use_ssl = true
request = Net::HTTP::Post::Multipart.new("/api/projects/:api_token/files/:file_id/locales/:locale_code", { "file" => UploadIO.new(file, "text/plain", file.path), "merge" => false, "ignore_missing" => false, "label" => "" })
http.request(request)
🔗Implementation Example in PHP:
<?php
$api_key = "sekret";
$file_path = "path/to/file.po";
$file_id = "1234";
$locale_code = "fr";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/files/" . $file_id . "/locales/" . $locale_code);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
// For PHP >= 5.5
curl_setopt($ch, CURLOPT_POSTFIELDS, array("file" => new CurlFile($file_path), "name" => $file_path));
// For Older PHP (< 5.5)
// curl_setopt($ch, CURLOPT_POSTFIELDS, array("file" => "@".$file_path, "name" => $file_path));
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false);
$response = curl_exec($ch);
print_r($response);
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 itselfname: 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.
🔗Implementation Example in Ruby:
require "net/http"
require "net/http/post/multipart" # gem install multipart-post
http = Net::HTTP.new("webtranslateit.com", 443)
http.use_ssl = true
request = Net::HTTP::Put::Multipart.new("/api/projects/:api_token/files", { "file" => UploadIO.new(file, "text/plain", file.path) })
http.request(request)
🔗Implementation Example in PHP:
<?php
$api_key = "sekret";
$file_path = "path/to/file.po";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/files");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
// For PHP >= 5.5
curl_setopt($ch, CURLOPT_POSTFIELDS, array("file" => new CurlFile($file_path), "name" => $file_path));
// For Older PHP (< 5.5)
// curl_setopt($ch, CURLOPT_POSTFIELDS, array("file" => "@".$file_path, "name" => $file_path));
$response = curl_exec($ch);
print_r($response);
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.
🔗Implementation Example in Ruby:
require "net/http"
http = Net::HTTP.new("webtranslateit.com", 443)
http.use_ssl = true
request = Net::HTTP::Delete.new("/api/projects/:api_token/files/:file_id")
http.request(request)
🔗Implementation Example in PHP:
<?php
$api_key = "sekret";
$file_id = "1234";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/files/" . $file_id);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
$response = curl_exec($ch);
print_r($response);
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 send a zip file containing all files in a project.
🔗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.