Skip to main content

Alignment - Step by Step

This chapter describes how to send original files/content plus any translated files/content to the Beebox and get translations aligned. We assume that you are already familiar with the Beebox and will skip more general explanations.


Align all files added to a project

This is the easiest way of aligning your files. Basically you copy all source files plus all translated files to the project. Then the Beebox will align all your content.

The aligned content can then be exported to XLIFF or sent to a TMS for further editing or approval.

The steps are:

  • Create a project and go to Settings 
  • Tick the Align by default options
  • Copy your source files to the project "in" directory
  • Copy your translated files to the project "out" directory, inside the language folders:
    • For example the French translation to \out\fr\marketing\myfile.docx
  • You can work in multiple target languages at the same time


Then instruct the Beebox to process your files:
  • Go to Source files
  • Click Process new files

Review the content.

Selectively align files using "instructions files"

Let us suppose that we have an English source file named “marketing\myfile.docx”. We further have existing French and Spanish translations of this file.

This is how you copy the files to the Beebox project directories:

  1. Copy the French translation to …\out\fr\marketing\myfile.docx
  2. Copy the Spanish translation to …\out\es\marketing\myfile.docx
  3. Copy an instructions file to …\in\marketing\myfile.docx.beebox
    This file contains Json and is UTF-8 encoded:
    { "align": { "locales": ["fr", "es"]  }  }
  4. Copy the original file to …\in\marketing\myfile.docx


When the Beebox then processes the source file it will see the instructions file and align the translated files. The Beebox now contains the source segments and the translations in French and Spanish. Note that when sending a source file without translations, you would just do step 4.


  • Always copy the source file at the end. This is important in automated setups where the Beebox polls the “in” directory for new/changed source files. We want to have the Beebox poll the source file only after we have properly copied the translations and the instructions.
  • Note that the translations are saved to the “out” directory and inside the language specific sub-directory. Make sure your Beebox project is configured for these exact languages.
  • Note that the translated files are given the exact same relative path (name) as the source file. This is essential or otherwise the Beebox will not find your files.
  • The instructions tell the Beebox that it shall extract and use the translations from the French and Spanish files. You must indicate the “locales” node with the list of languages (at least one).

There is a nice video tutorial:


HTML Macro for Confluence Cloud does not support the email rendering mode.

If you're experiencing issues please see our Troubleshooting Guide.


Align files using the API

Instead of copying files to the “in” and “out” directories of a Beebox project, you can of course do this with the API.

The steps are:

  1. Send the French translation in the body of API method:
    (PUT) /api/files/file?token=&locale=fr&folder=&filename=marketing\myfile.docx
  2. Send the Spanish translation in the body of API method:
    (PUT) /api/files/file?token=&locale=es&folder=&filename=marketing\myfile.docx
  3. Send the instructions file in the body of API method:
    (PUT) /api/files/file?token=&locale=en&folder=&filename=marketing\myfile.docx.beebox

    This file contains Json and is UTF-8 encoded:
    { "align": { "locales": ["fr", "es"]  }  }
  4. Send the English original content in the body of API method:
    (PUT) /api/files/file?token=&locale=en&folder=&filename=marketing\myfile.docx

API documentation.

Example of a post-editing workflow

This is a frequent use-case for which other tools do not propose a solution and which the Beebox handles in a breeze.

The scenario: You send a source file “myfile.docx” to the Beebox for translation into French.The Beebox translates and saves the result to “…\out\fr\myfile.docx”. The customer opens the translated file and makes changes to it or types inline comments:

How do you get the changes or comments back into the Beebox and your TMS? Changes are needed to update Beebox and TMS memories; Comments need to go to the translation team to take action…

In the Beebox simply update the translated file, the location being unchanged: …\out\fr\myfile.docx.

Add the instructions file with the “align” node and update the date of the source file. The latter is required or otherwise the Beebox will not process the file again: It looks at the source file date and only picks source files only if the creation or modification date has changed.

Once this is done, the Beebox will read source and translation, align them and incorporate all the changes done.

The complete scenario is:

  • Initial translation:
    • Send source file to Beebox and wait until translated file is created.
    • Deliver file to customer.
  • Post editing:
    • Customer edits the translated file and sends it back to you
  • Second translation:
    • You save the file to the “out” directory and update the source file’s date
    • The Beebox will incorporate all the changes both in the source file (if any) and the translated file (edits, comments).
    • The Beebox will create the translated file with any further updates done by the translation team.
    • Deliver file to customer.
  • Post editing, again:
    • If the customer does further editing, start over again…




JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.