Manage your files

Once the translation project is created (see the project creation flow here), you can start managing your source and/or reference files. However, you must pay attention to format restrictions, and recommendations.

Project API file-handling actions

These are the main actions that you can perform when managing your files with our Project API:

File action	When?
Add source file	When creating your project, and before starting it.
Add reference file	This is optional. When creating your project, and before starting it.
Download file and Download reference file	When the project has a "Finished" status.
Delete file and Delete reference file	You can remove your files once they are downloaded or while creating the project (draft status). You cannot delete a file when the project has already started (with "Active" status).

Caution

If you delete a file, this will be permanently removed from the project and you won't be able to recover it.

File types

Source files

These are those files in original (source) language that need to be translated by LanguageWire experts (or by Artificial Intelligence technology).
When adding a source file to your project, make sure you apply the outlined suggestions:

• You can only add 1 file per endpoint request.
• The maximum allowed size is 3Gb per file.
• Translation projects can support up to 400 files maximum.

• The source file name is a mandatory field.

Reference files

Reference files are optional, and provide context to our experts when working on your project. They have the same restrictions than those applied to source files.

• Some examples of reference files are: HTML for websites, but also images, PDFs, etc.
  
• The extensions doc, docx, ppt and pptx are allowed as these are converted to PDF automatically.
  
• The reference file name is a mandatory field.

Info

In case of a HTML, you should include the .ZIP container with all the assets: images, style CSS, etc.

Preview option

If you want your reference file to be the default preview option for our experts (so they can visualise it while translating your file), use the same name for both, your reference and source file. Both names should match.

Restrictions

File formats

Our API accepts all types of file formats, to name some:

.doc, .docx, HTML, HTM, .pot, .potx, .pps, .ppt,
.pptx, .rtf, .txt, .vsd, .vsdx, .xls, .xlsx, .xlt,
XML, XLIFF, JSON, DITA, properties files, string files and InDesign files (IDML and INDD)*

Caution*

We will need to agree on the file formats that are going to be sent when setting up the production account.
Even though the API can handle any file format, an additional processor might be needed to extract the information from your files or translation packages. 📧 Contact us for more details.

Translations according to formats

When using different file formats, you should keep in mind that not all elements in the file are translated with our Project API. See in this table which elements are included and excluded from translation by default for most common formats.

Type of format	Included in translation	Excluded from translation	Things to consider
Microsoft Word files (.docx)	- All editable text, including: Headers, Footers, Text boxes, etc. - Index entries.	- Hidden text. - Table of contents. - Index. - Comments - Drop-down list.	- Non-editable text in embedded images or graphs is not translated. - Index and Table of Contents, if correctly created in the source file and linked to existing content there, is automatically updated in translation file.
Excel files (.xlsx )	- All editable text in regular cells. - Content from all unhidden sheets is included. - Editable text from charts and text boxes. - Headers and footers.	- Hidden columns, rows, and sheets. - Sheet labels. - Cells containing formulas, including dates. - Notes. - Comments.	Only monolingual XLSX are supported out of the box.
Visio files (vsdx and vdx)	"Regular" editable text.	- Locked layers. - Invisible layers. - Non-printable layers. - Screen tips. - Comments.	.vsd format is not supported.
PowerPoint files (pptx)	- All editable text on slides. - Text boxes. - Headers and footers. - Speakers notes. - Speakers notes. - Hidden text.	- Master slides. - Comments.	Non-editable text in embedded images or graphs is not translated.
TXT	All plain text is translated.	------	------
RESX	Content tagged as <value>.	- Comments. - Content tagged as <metadata> and <resheader>	------
HTML	All plain text including drop-down lists.	------	------
UDF (more information at the end of this page)	It includes for translation value of “text” (it is a valid html-chunk).	- Metadata. - Content considered non-translatable strings, e.g., uuid-strings, mime-type strings, ISO 8601 date-time strings, base64 encoded strings, any non-string value (JSON Boolean, JSON numbers, etc.)	“Comments” are converted into notes for translator.
SRT	All editable content included within timestamps.	Timestamps.	Timestamps are displayed as notes for translators.
VTT	All editable content included within timestamps.	- Timestamps. - Metadata. - Styling information	Timestamps are displayed as notes for translators.

Missing your file format in this list? If you have any other file format that is not listed here, and/or these default settings do not meet your needs for content processing, please contact us and we will guide you on other solutions.

File names

Files added to a translation project must be identified by a name. This is a mandatory field.
When choosing a name for either your to-be-translated source file and/or your reference file, you must take into consideration the following restrictions:

File name restrictions
✔️ The file name can only contain characters from ISO/IEC 8859-1 standard, which is the default encoding of documents delivered via HTTP. See the full list of allowed characters here. ✔️ The file name must not exceed 100 characters in length.
❌ Exclude control characters. ❌ Characters that are considered "reserved" or "illegal" by either Windows or Linux are not allowed.

Tip

If you can save a file with a given name on Windows & Unix, then it should be considered valid in our API as well (the only limitation that it has <=100 characters).

Universal Document Format (UDF)

UDF is a format created by LanguageWire to handle HTML documents in a structured way.
We represent UDF files using the 'content-type' header application/vnd.lw.api+json.

It is designed to facilitate the translation of web content, allowing for better handling of HTML elements and metadata. UDF files were introduced in 2014 and some integrations still find it valuable to work with.

UDF files consists of frames which are finished pieces of HTML. It is represented as a JSON object with the following attributes:

• frames: object
  • The document consists of zero or more frames.
• metadata: object
  • An optional object with application-specific string keys, associated with the whole document. It is not touched during translation.
• comment: string
  • An optional comment that helps a translator to understand document content better.
• preview: string
  • An optional URL to a publicly accessible page with the document preview. The preview demonstrates how the original content looks with styles and images, being integrated into the layout. The page must be accessible without any authorization. The URL must be absolute with the HTTP or HTTPS scheme, no longer than 256 characters.

A frame in its turn has the following structure:

• text: string
  • A text for translation in HTML format. The text can be empty but cannot be null.
• metadata: object
  • An optional object with application-specific string keys, associated with the frame. It is not touched during translation.
• comment: string
  • An optional comment that helps a translator to understand frame content better.

UDF example:

{
  "frames": [
    {
      "text": "<h1>Welcome to LanguageWire</h1><p>This is a sample UDF file.</p>",
      "metadata": {
        "author": "John Doe",
        "version": "1.0",
        "moduleId": "123"
      },
      "comment": "This is the main header of the page."
    }
  ],
  "metadata": {
    "pageId": "12345",
    "language": "en"
  },
  "preview": "https://example.com/preview"
}