This guide is designed to help you identify parsing discrepancies in AsciiDoc (.adoc, .asciidoc) and Markdown (.md) files, validate file syntax, and ensure that any support tickets raised contain the necessary details for a rapid resolution.

When processing AsciiDoc or Markdown files for translation, a parsing or configuration issue typically manifests in XTM Workbench in one of the following ways:

• Incorrect Segmentation: Sentences or paragraphs are broken up unnaturally, or multiple separate blocks are incorrectly merged into a single segment.

• Incorrect Translation Scope: Translatable text is completely missing from XTM Workbench, or non-translatable text (such as code, variables, or image paths) is extracted as translatable content.

• Exposed Syntax: Raw AsciiDoc or Markdown markup language or structural tags are visible as plain text inside a translatable segment instead of being converted into inline tags.

• Target File Errors: The translation process completes, but the final generated target file contains unexpected structural anomalies or layout corruption.

Before opening a support ticket, it is highly recommended to verify whether the source file's formatting is behaving as expected:

• Use an AsciiDoc or Markdown Interpreter: If a segment looks incorrect in XTM Workbench, check the source file fragment in an external AsciiDoc or Markdown interpreter or preview tool.

  • If the external tool renders the text with errors, the source file's syntax contains typos or layout issues that must be corrected on your side.

  • If the syntax renders perfectly in standard tools but behaves unexpectedly in XTM, the file processing configuration or parser rules may need to be adjusted.

• Utilize Test Projects: If you are dealing with a large batch of documents or new structural templates, upload a small sample file to a small test project first to verify the extraction layout before launching the main project.

To ensure our team can investigate and resolve your processing issue efficiently without unnecessary back-and-forth communication, please provide the following details when opening a ticket:

• Project Identifier: The exact XTM Project Name or Project ID.

• File Name: The specific file name containing the issue (especially critical if you are utilizing file-joining features, or upload multiple files to the project).

• Segment Context: The specific segment number in XTM Workbench, or the corresponding line number from the source file.

• Visual Reference: A screenshot of the affected segment in XTM Workbench or a snippet of the source code. A well-sized screenshot from Workbench can provide all of the previously listed required information at once.

• Expectation vs. Reality: A brief description of what is currently wrong and how you expect that specific text to be segmented or processed.

• Target Language: The target language code (required if the issue involves the finalized target file generation).

Once a ticket is submitted, our support team will analyze the intermediate layout of the file to determine the path to resolution:

• Configuration Changes: If the issue can be resolved by adjusting your filter template or optimizing custom regex rules, the update can be applied directly by support. These corrections are typically completed within a few days.

• Development Fixes: If the issue is caused by an unhandled syntax edge-case or a bug in the core parser, a task will be escalated to our development team to update the system framework. Because these fixes require code changes and testing cycles, resolution timelines will vary and take longer to deploy.