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 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: 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

NEW If your file is a JSON file, you can request for this file using JSONP by adding the parameter ?callback=callbackName to the URL. This doesn’t work for other file formats.

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.

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]

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

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

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 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" => "", "low_priority" => false })
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, 'PUT');
  curl_setopt($ch, CURLOPT_POSTFIELDS, array("file" => "@".$file_path, 'name' => $file_path));
  // Added in PHP 5.5.0 with false as the default value. PHP 5.6.0 changes the default value to true.
  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 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.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_path));
  //Added in PHP 5.5.0 with false as the default value. PHP 5.6.0 changes the default value to true.
  curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false);
  $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.