WebTranslateIt API » File API

The File API is composed of 4 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 NEW — Serves all files in a project as a zip archive

Show File

This endpoint is accessible by both private and public 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 for a YAML file: https://webtranslateit.com/api/projects/98e71ee45042066f1053ed900b4e8f4ec1f98451/files/1943/locales/en Example for a Gettext file: https://webtranslateit.com/api/projects/c14361bf252ae0add4d2231f231392b775c49079/files/1820/locales/en

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 fil, 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.

Some programming languages’ implementation of If-Modified-Since is buggy. This is the case of all version of PHP older than 5.2.10. In that case you can add the timestamp of the date of last modification as an extra parameter to your request, like so:

/api/projects/:project_token/files/:master_project_file_id/locales/:locale_code?last_updated_at=:timestamp [GET]

Example: https://webtranslateit.com/api/projects/98e71ee45042066f1053ed900b4e8f4ec1f98451/files/1943/locales/en?last_updated_at=1256953732

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 private 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 [PUT]

Parameters:

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

Optional parameters

  • name, the file name,
  • 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.

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" => "", "low_priority" => false })
http.request(request)

Implementation Example in PHP:

<?php
  $api_key = "sekret";
  $file_path = "path/to/file";
  $file_name = "messages.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, 'PUT');
  curl_setopt($ch, CURLOPT_POSTFIELDS, array("file" => "@".$file_path, 'name' => $file_name)); 
  $response = curl_exec($ch);
  print_r($response);
  curl_close($ch);
?>

Create File

This endpoint is only accessible by the private 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.

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), "low_priority" => false })
http.request(request)

Implementation Example in PHP:

<?php
  $api_key = "sekret";
  $file_path = "path/to/file";
  $file_name = "messages.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);
  curl_setopt($ch, CURLOPT_POSTFIELDS, array("file" => "@".$file_path, 'name' => $file_name)); 
  $response = curl_exec($ch);
  print_r($response);
  curl_close($ch);
?>

Delete File

This endpoint is only accessible by the private API key and is used to delete a master language file.

/api/projects/:project_token/files/:file_id [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 private and public 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.