This article is intended for developers integrating with the Smartling platform via API. If you are uploading documents using the Smartling Dashboard, please refer to the article for dashboard users instead.

Extension	.doc, .docx, .docm, .xlsx, .ppt, .pptx
Smartling Identifier	doc, docx, docm, xlsx, xlsxtemplate, pptx
Resources	for developers

Smartling supports Microsoft Office file formats for Word (.doc, .docx, .docm), Excel (.xlsx), and PowerPoint (.pptx) for versions 2007 and later, as well as Smartling Excel format (xlsxTemplate).

Important considerations

Hyperlink translation is supported for all supported file types via file rewrite rules or a directive.
Multiple comma-separated noTranslate styles are supported for .doc, .docx, .docm, and .xlsx files.
Each Excel cell must not exceed 32,000 characters, in accordance with Excel's specifications.
Content can be excluded from translation directly within the document using a NOTRANSLATE style. For more details, refer to our Translating Microsoft Office Documents article.
Alternatively, the style(s) to be excluded can be specified using a File API directive.
Excel files can be parsed using Smartling Excel format. When uploading the file specify xlsxTemplate as the fileType, and use the string instruction and character limit directives.

Directives

File directives are supported via the Smartling API only, in the following format:

API Parameter

smartling.[directive_name] = [value]

Tip: Consult your Customer Success Manager or Solutions Architect for more information on custom file directive templates for your project.

Translate Master Slides

Directive	smartling.process_master_slides
Values	true\|false\|TRUE\|FALSE\|yes\|YES\|no\|NO\|off\|OFF
File Format	PPT, PPTX
Smartling Translate Supported	Yes
Description	This directive decides if Smartling should ingest content from master slides for translation. By default, Smartling will not ingest content found on master slides (false).
Examples	`curl -X POST -H "Authorization: Bearer {TOKEN}" -F "file=@master_page_parse.docx" -F "fileUri=master_page_parse.docx" -F "fileType =DOCX" -F "smartling.process_master_slides=true" "https://api.smartling.com/files-api/v2/projects/{PROJECT_UID}/file"`

Translate Handout Slides

Directive	smartling.process_handout_slide
Values	true\|false\|TRUE\|FALSE\|yes\|YES\|no\|NO\|off\|OFF
File Format	PPT, PPTX
Smartling Translate Supported	Yes
Description	This directive decides if Smartling should ingest content from the handout slide. By default, Smartling will parse content from handout slide (true).
Examples	`curl -X POST -H "Authorization: Bearer {TOKEN}" -F "file=@master_page_parse.docx" -F "fileUri=master_page_parse.docx" -F "fileType =DOCX" -F "smartling.process_handout_slide=false" "https://api.smartling.com/files-api/v2/projects/{PROJECT_UID}/file"`

Translate Slide Notes

Directive	smartling.process_slide_notes
Values	true\|false\|TRUE\|FALSE\|yes\|YES\|no\|NO\|off\|OFF
File Format	PPT, PPTX
Smartling Translate Supported	Yes
Description	This directive decides if Smartling should ingest notes from slides. By default, Smartling will parse text content from notes to slides (true).
Examples	`curl -X POST -H "Authorization: Bearer {TOKEN}" -F "file=@notes_off.docx" -F "fileUri=notes_off.docx" -F "fileType =DOCX" -F "smartling.process_slide_notes=false" "https://api.smartling.com/files-api/v2/projects/{PROJECT_UID}/file"`

Translate Master Notes

Directive	smartling.process_master_notes
Values	true\|false\|TRUE\|FALSE\|yes\|YES\|no\|NO\|off\|OFF
File Format	PPT, PPTX
Smartling Translate Supported	Yes
Description	This directive decides if Smartling should ingest notes from master slides. By default, the parser will not ingest content from notes to master slide (false).
Examples	`curl -X POST -H "Authorization: Bearer {TOKEN}" -F "file=@master_notes_on.docx" -F "fileUri=master_notes_on.docx" -F "fileType =DOCX" -F "smartling.process_master_notes=true" "https://api.smartling.com/files-api/v2/projects/{PROJECT_UID}/file"`

Translate Comments

Directive	smartling.process_user_comments
Values	true\|false\|TRUE\|FALSE\|yes\|YES\|no\|NO\|off\|OFF
File Format	XLS, XLSX \| PPT, PPTX \| DOC, DOCX, DOCM
Smartling Translate Supported	Yes
Description	This directive decides if comments in the file are ingested for translation. The default behavior for .xls and .xlsx is on. The default behavior for .ppt, .pptx, .doc, .docx, and .docm is off.
Examples	`curl -X POST -H "Authorization: Bearer {TOKEN}" -F "file=@user_comments_on.docx" -F "fileUri=user_comments_on.docx" -F "fileType =DOCX" -F "smartling.process_user_comments=true" "https://api.smartling.com/files-api/v2/projects/{PROJECT_UID}/file"`

Include String Instructions

Directive	smartling.instruction_column=B
File Format	xlsxTemplate This directive is only supported for Smartling Excel files. String instructions must be listed alongside the applicable string in column B, excluding B1 which is a header.

Include Character Limits

Directive	smartling.character_limit_column=C
File Format	xlsxTemplate This directive is only supported for Smartling Excel files. Character limits must be listed alongside the applicable string in column C, excluding C1, which is a header. Numbers must be formatted as General, Text, or Accounting formatting types to be ingested as character limits.

Exclude Content from Translation

Directive	smartling.no_translate_style
Values	A comma-separated list of no-translate style names, e.g.: STYLE1, STYLE2
File Format	XLS, XLSX \| DOC, DOCX, DOCM
Smartling Translate Supported	Yes
Description	This directive excludes specific styled content from translation. Smartling recognizes two default no-translate styles: SLNOTRANSLATE and NOTRANSLATE. If you include this directive, only the styles specified in the directive will be treated as no-translate styles. The directive overrides the default styles. Paragraphs with the specified style names applied will not be ingested for translation. Learn more about excluding content using styles here. Note: For DOC/DOCX/DOCM files, the styles referred to by this directive are paragraph styles. This means content is excluded at the paragraph level, if a paragraph is marked with a no-translate style, the entire paragraph will be excluded from translation.
Examples	curl -X POST \ -H "Authorization: Bearer {TOKEN}" \ -F "file=@specific_no_translate.docx" \ -F "fileUri=specific_no_translate.docx" \ -F "fileType=DOCX" \ -F "smartling.no_translate_style=MyStyle1,MyStyle2" \ "https://api.smartling.com/files-api/v2/projects/{PROJECT_UID}/file"

Exclude Hidden Content from Translation

Directive	smartling.no_translate_hidden_elements
Values	Values depend on the file type: Excel files: sheets \| rows \| columns Word files: text PowerPoint: slides
File Format	XLS \| XLSX \| DOC \| PPT
Smartling Translate Supported	Yes
Description	By default, parser will ingest: All content in a spreadsheet, including hidden sheets, columns and rows. All content in the Word document, including hidden text. All content in the PowerPoint, include hidden slides. With this directive, you can exclude hidden content from being ingested to Smartling for translation. Multiple values can be excluded by comma separation.
Examples	smartling.no_translate_hidden_elements=rows,columns

Translate Hyperlinks

Directive	smartling.translate_hyperlinks
Values	true\|false\|TRUE\|FALSE\|yes\|YES\|no\|NO\|off\|OFF
File Format	XLS, XLSX \| PPT, PPTX \| DOC, DOCX, DOCM
Smartling Translate Supported	Yes
Description	This directive decides if Smartling should ingest hyperlinks for translation. The default value is "false". If set to "false", only the link text is ingested as translatable text, as part of the source string. The link address is not ingested for translation. If set to "true", the link text is ingested as part of the source string; the link address is uploaded as a separate string to translate.

Variant Strategy

Directive	smartling.variants_strategy
Values	context_match \| repetition_indexed \| none
File Format	XLS, XLSX \| PPT, PPTX \| DOC, DOCX, DOCM
Smartling Translate Supported	Yes
Description	Values are case-insensitive. The default value is repetition_indexed, which means that the string indexes as variants for repeated strings functionality is enabled. context_match enables ICE variants functionality. ICE variant is defined as a variant on a string calculated by the exact character text of the preceding and following strings, if any. This combines the two surrounding strings with a separator character sequence to differentiate between ending and starting strings in a document.
Examples	smartling.variants_strategy=context_match

Translate Sheet Names

Directive	smartling.translate_sheet_names
Values	true\|false\|TRUE\|FALSE\|yes\|YES\|no\|NO\|off\|OFF
File Format	XLS, XLSX
Smartling Translate Supported	Yes
Description	The default value is off. The name of each sheet is ingested as a translatable string, even if there is no content on the sheet. To include sheet names for translation, use true, yes, on. To prevent sheet names from being ingested into Smartling as a translatable string, use false, no, off (default).
Examples	smartling.translate_sheet_names=true

Excel Cell Segmentation

Directive	smartling.excel_cell_segmentation
Values	none \| newline
File Format	xlsxTemplate, XLSX
Description	This directive controls how multi-line cell content is segmented for translation. By default (none), the entire cell content is treated as a single translatable string. When set to newline, each newline-separated line within a cell is extracted as an independent translatable string. This improves translation memory leverage and provides a better experience for translators working in the CAT Tool. When newline is used, placeholder indices are re-numbered per line so translators see `{0}`, `{1}`, etc. in each substring. If a cell contains mixed formatting (for example, a bold first line and an italic second line), each line retains its original formatting after translation. Blank lines and any newlines at the beginning or end of a cell are also preserved in the translated file.
Examples	API parameter: `smartling.excel_cell_segmentation=newline` curl -X POST \ -H "Authorization: Bearer {TOKEN}" \ -F "[email protected]" \ -F "fileUri=multiline-content.xlsx" \ -F "fileType=xlsxTemplate" \ -F "smartling.excel_cell_segmentation=newline" \ "https://api.smartling.com/files-api/v2/projects/{PROJECT_UID}/file"

Control Locale Identifier in the Header

Directive	smartling.locale_column_header_format
Values	One or more of the following variables: ${locale.id} ${language.id} ${country.id} ${language.description} ${country.description}
File Format	XLS \| XLSX
Description	External directive that specifies a column header format for the column with translations for particular locale in downloaded xlsx file with multi-locale translation. For instance, for the fr-FR locale, the following format: ${language.description} (${country.description}) results in this header in the translated file: French (France)
Examples	smartling.locale_column_header_format = `${locale.id}` [`${country.description}`] smartling.locale_column_header_format = `${languahe.id}` (`${country.id}`) smartling.locale_column_header_format = language: `${languahe.id}`, country: `${country.description}`

Exclude Content With a Specific Style

Directive	smartling.no_translate_placeholder_style
Values	A character style name/comma-separated style names, e.g. STYLE1, STYLE2
File Format	DOC, DOCX, DOCM
Smartling Translate Supported	Yes
Description	Any text element marked with the character-type style names, provided by this directive, will not be ingested for translation. There is no default value for this directive.
Examples	smartling.no_translate_placeholder_style=STYLE1,STYLE2

Translate Revisions

Directive	smartling.translate_revisions
Values	true\|false\|TRUE\|FALSE\|yes\|YES\|no\|NO\|off\|OFF Default: false\|FALSE\|\|no\|NO\|off\|OFF
File Format	DOCX
Smartling Translate Supported	Yes
Description	By default, Smartling translates the latest version of a document with Accept-All-Revisions before parsing the document on strings/parts. This directive allows you to translate all revisions and have translated history of revisions, by keeping all changes/revisions as special blocks (<ins>, <del>,<span> html tags). You may also want to use smartling.process_user_comments directive to translate comments to revisions.
Examples	`curl -X POST -H "Authorization: Bearer {TOKEN}" -F "file=@user_comments_on.docx" -F "fileUri=user_comments_on.docx" -F "fileType =DOCX" -F "smartling.translate_revisions=true"` `"smartling.process_user_comments=true" "https://api.smartling.com/files-api/v2/projects/{PROJECT_UID}/file"`

Trim Whitespace

Directive	smartling.whitespace_trim
Values	on\|yes\|true or off\|no\|false or leading\|trailing The default value is on
File Format	DOC, DOCX, DOCM \| PPT, PPTX \| XLS, XLSX, XLSX_TEMPLATE
Smartling Translate Supported	Yes
Description	A whitespace is any character or series of characters that represent horizontal or vertical space in typography. When rendered, a whitespace character is not a visible mark, but does occupy an area or space on a page. Although whitespaces are necessary within a string (typically to separate words), unnecessary whitespaces can be found at the start of a string (leading) and at the end of a string (trailing). With this directive, you can trim whitespaces, as it enables or disables whitespace trim management for the ingested strings. By default, the leading and trailing whitespaces are trimmed. You can choose to disable trimming or specify trimming for leading or trailing whitespaces.
Examples	`smartling.whitespace_trim=on` Smartling will trim leading and trailing whitespaces (default) `smartling.whitespace_trim=off` Smartling will not trim leading or trailing whitespaces `smartling.whitespace_trim=leading` Smartling will trim only leading whitespaces `smartling.whitespace_trim=trailing` Smartling will trim only trailing whitespaces

Tag Reduction Strategy

Directive	smartling.tag_reduction_strategy
Values	default\|off
File Format	DOCX, XLSX, PPTX, IDML
Description	When set to default, this directive instructs the parser to detect the default font within ingested strings to reduce the number of tags included in strings for translation, thereby decreasing translation effort and improving future leverage.
Examples	smartling.tag_reduction_strategy=default

Custom Placeholder Format

Directive	placeholder_format_custom
Values	1) Custom Java regular expression. 2) NONE - disables any current custom placeholders
File Format	DOCX
Description	Specifies a custom placeholder format. Any text in your file matching the regular expression you provide will be captured as a placeholder.
Examples	smartling.placeholder_format_custom=\{([^}]+)\} Any characters surrounded by curly brackets, e.g., {first name}, will be treated as a placeholder.

See Placeholders in Resource Files for more on placeholders.

Translating Microsoft Office Documents via API