Using API to create continuous localization projects

This article provides a simple recipe to create projects using the Continuous API. One of the most aspects to understand is that the tag provide in the creation step will uniquely identify a project among other CI projects in Bureau Works.

Normally a project will follow these states in Bureau Works:

1. PREPARING - draft state, when you can still add files to the project
2. PENDING - it means that project has been analyzed and a cost structure may be attached
3. APPROVED - the project is sent to production - files can no longer be added
4. DELIVERED - final state, this is good for production
5. INVOICED - project is in receivables

A continuous project will normally run this path, in the above sequence. What this means is that you can pull files from any of these states (assuming that they exist), but the content will vary. For example, in PREPARING state, a job most likely will be a mix of Machine Translation, if enabled, and the Translation Memories attached to the project - which is great! However if you need production strings, you will need to pull from DELIVERED state.

This article assumes you're comfortable with the authentication mechanism in the API.

Create Project and Upload Files

Invoke the following endpoint:

POST https://<SUB>.bureau.works/api/pub/v1/project/async/continuous/<TAG>

Substitute <SUB> for your Bureau Works handle, and <TAG> with a meaningful representation of your project, such as ios, android, Windows, etc.

This endpoint receives a form-data as input, with the following parameters:

• file - multipart file
• reference - something for your reference
• languages - a list/array with the Bureau Works languages codes (please refer to https://dev.bureau.works/#languages)

If the languages parameters is not informed, Bureau Works will assume the default languages set up in the Client's profile. If none can be found, then this endpoint will throw an error.

In case of success will you receive a 200 message, with a body like this:

{
 "id": "9999999-3333-4555-2223-964c1e52cb88",
 "status": "NEW",
 "data": {
 "projectId": 999999,
 "fileName": "Resources.resx",
 "fileHash": "867423243877g24dg9gs2gg2sg23gs239gsg",
 "productTag": "dispatch"
 },
 "error": null
}

This endpoint, if invoked in sequence with different files, will add the files to the same project identified by the <TAG>.

Projects created with this method are normally discoverable and access in the Bureau Works web UI, at https://<SUB>.bureau.works.

Downloading Files from Continuous Localization Projects

To download files, use the following endpoint:

GET https://<SUB>.bureau.works/api/pub/v1/project/continuous/<TAG>/<FILENAME>/

This endpoint has an optional query parameter:

• status - if provided, will try to find the desired state from the list above

When downloading files, the state will follow a fallback mechanism. For example, if a PREPARING project is not found, it will automatically try to fetch the project with the same tag in PENDING state. If none found, it will fallback to DELIVERED, and so on.

The response of this endpoint can be saved locally as a zip file, containing all translations for all languages setup in the project.

For each given tag, it is possible to create a configuration in the Client profile that defines a directory structure for each one. This way it becomes easy to download packages ready for deployment in each project's structure. If none provided, the zip structure will be:

• /
  • lang1
    • file.xml
    • file2.json
  • lang2
    • file.xml
    • file2.json
  • lang3
    • file.xml
    • file2.json