Choosing a Project Structure for Translation

How to organize source and translated content into folders and branches, and how the agent determines which layout to use.

The Default Project Layout

By default, Oxygen Content Fusion organizes source and translated content into one folder pair per language, all on the same branch:

  • The English source content is stored in an en/ folder.
  • Each target language is stored in its own top-level folder, named after the language tag (for example, fr-FR/ or de-DE/).
  • Inside each language folder, files use the same relative paths as their English counterparts (for example, en/topics/install.dita and fr-FR/topics/install.dita).
  • The translation index is stored at .contentfusion/i18n/translation-index.xml.

This is the layout the agent assumes when it sets up a project for the first translation job. It is also the layout described throughout this documentation, unless stated otherwise.

How the Agent Determines the Layout

When a translation job starts, the agent determines which layout to use in three steps:

  1. If a custom layout is documented in agent-instructions.md, the agent follows it.
  2. Otherwise, the agent tries to detect the layout from the existing content. If you use a non-default layout, document it in agent-instructions.md so the agent can follow it reliably instead of inferring it each time.
  3. If no layout is detected, the agent uses the default layout described above.

Choosing a Custom Layout

If the default layout does not fit your project, you can use a different one, as long as it meets these constraints:

  • For compatibility with other tools, keep all DITA resources in subfolders of the folder that contains the DITA map.
  • Keep each source file in the same relative location in every target language as in the source language. Otherwise, links must be updated during translation, which is error-prone. For example, identifying French files with an -fr suffix is not recommended.
  • Store the source and target languages on the same branch. For example, if you want to keep an editing branch that contains only English files, create a parallel branch that contains both the English source and all translations in the default per-language layout, then merge the editing branch into it before each translation job.

Document any non-default layout in detail in agent-instructions.md so the agent follows it. See Customizing the Translation Behavior.