Document Translator Service

3 min read

The Document Translator translates Word, Excel, and PowerPoint documents while preserving their structure and formatting where possible.

Supported formats

Microsoft Word (.docx)
Microsoft Excel (.xlsx)
Microsoft PowerPoint (.pptx)

Translated documents retain their original file format and are returned in the chat. Translator V2 can also apply a glossary, Translation Memory, text post-processing, and document font settings.

Supported content

Format	Content translated	Additional behavior
Word	Paragraphs, tables, nested tables, headers, footers, and supported textboxes	Document structure and supported run formatting are preserved where possible.
Excel	Textual cell values	Formulas remain unchanged and are not sent for translation.
PowerPoint	Text shapes, grouped shapes, tables, chart labels, speaker notes, and text in slide masters and layouts	Hyperlink addresses and supported run formatting are preserved where possible.

Known limitations

General

Large documents can be constrained by the configured token and rate limits or by language-model provider quotas.
Complex document structures may require review after translation.

Word

Footnotes and comments are not translated.
Complex hyperlink structures may not expose all display text for translation.
Automatically generated tables of contents may require a refresh in Microsoft Word after translation.

Excel

Sheet names, comments, text in drawings or textboxes, and text contained in formulas are not translated.
Formulas are preserved rather than translated.

PowerPoint

Comments, SmartArt or diagram content, and dynamic fields are not guaranteed to be translated.
Highly complex run formatting may be simplified when the original run structure cannot be preserved safely.

Configuration

Document translation settings are configured within translatorUserConfig. Settings omitted from the configuration use the platform defaults.

Example

json

{
  "translatorUserConfig": {
    "languageModel": "AZURE_GPT_4o_2024_1120",
    "additionalLLMOptions": {},
    "maxTokensPerTranlationRequest": 500,
    "maxTokenPerMinute": 40000,
    "saveTranslationCallsEnabled": false,
    "translationExamplesIgnored": false
  }
}

Parameters

Parameter	Description	Default
`languageModel`	Language model used for document translation. If omitted, the platform default is used.	`AZURE_GPT_4o_2024_1120`
`additionalLLMOptions`	Additional options passed to the configured language model, such as `{"seed": 42}`.	`{}`
`maxTokensPerTranlationRequest`	Maximum number of tokens translated in one request. Longer content is split into multiple requests.	`500`
`maxTokenPerMinute`	Maximum token rate available to document translation.	`40000`
`saveTranslationCallsEnabled`	Whether individual document-translation calls are saved in the chat message.	`false`
`translationExamplesIgnored`	Whether configured translation examples are ignored.	`false`
`allowedInputLanguages`	Optional list of input languages considered during source-language detection for language-specific translation examples and glossary entries. If omitted, all supported languages are allowed.	All supported languages

Document font configuration

documentFontConfig controls the typefaces applied to translated documents. It can define a general fallback and language-specific settings.

Example

json

{
  "documentFontConfig": {
    "defaultTypeface": "Arial",
    "typefaceByTargetLanguage": {
      "Traditional Chinese (Hong Kong)": {
        "defaultTypeface": "Arial",
        "segmentTypefaces": {
          "chinese": "Microsoft JhengHei"
        }
      }
    }
  }
}

Parameters

Parameter	Description	Default
`defaultTypeface`	Fallback typeface applied when no target-language override matches.	`null`
`typefaceByTargetLanguage`	Typeface settings keyed by target-language name. A value can be a typeface name or a per-language configuration object.	`{}`
`defaultTypeface` within a language	Default typeface for that target language.	`null`
`segmentTypefaces.chinese`	Optional typeface applied to Chinese text segments in PowerPoint documents.	Not configured

In Word and PowerPoint documents, recognized symbol-only and icon-font runs retain their original typeface to prevent missing glyphs.

Advanced prompt configuration

Most spaces should use the platform prompt defaults. Administrators can optionally override the document translation prompts through translatorPromptConfig.

Parameter	Description	Default
`systemPromptInstruction`	System instruction used for document translation.	Platform default
`userMessageTemplate`	Template used to present document text and translation context to the language model.	Platform default

Template variables

userMessageTemplate supports all variables below. systemPromptInstruction supports the same variables except formatted_text_pieces.

Variable	Description
`format_style`	Formatting style used to structure document text for translation.
`input_language`	Detected source language, when available.
`output_language`	Selected target language.
`glossary`	Glossary context used to conditionally include terminology guidance.
`glossary_text`	Prepared glossary guidance for the translation request.
`formatted_text_pieces`	Document text formatted for translation.

Only customize prompts when necessary. Preserve the variables used by the platform defaults, together with the structural markers, span counts, and formatting instructions. Removing them can omit source content or translation context and may cause translated documents to lose content or formatting.