How does a TMS connector handle partially translated files?

Last reviewed: September 20, 2026

What decides what a connector writes into untranslated strings?

Four settings, applied together, determine what a destination system receives when a translation is incomplete:

• Delivery trigger — Whether the connector waits for completion or delivers on every change. Smartling's Repository Connector exposes this as a downloadTranslations trigger of COMPLETED (the default) or ONCHANGE; the hosted GitHub Connector delivers a translation pull request when the job completes, with an Early Delivery option for a pre-published pass. The hold, per-locale, and staged-release controls that govern this layer are covered on the batch translation publishing control page.
• Retrieval type — Which translations qualify for inclusion. Smartling's Files API accepts published (only strings in the Published step, with pre-published strings included), pending (any saved translation, including in-progress ones), pseudo (source text lengthened for layout testing), and contextMatchingInstrumented (Smartling API Specification, Files API). The Repository Connector supports PUBLISHED, PENDING, and PSEUDO, defaulting to PUBLISHED.
• Fallback for missing translations — What replaces a string that has no qualifying translation. Smartling's includeOriginalStrings parameter returns the source-language string by default, or an empty string when set to false; the parameter is supported only for Gettext, Java properties, custom XML, Android XML, and JSON files (Smartling Help Center, Repository Connector FAQ). For a running application the source fallback is usually safer, because most i18n libraries render an empty value as a blank label rather than falling back on their own.
• Completion scope — Which strings must be done before the file counts as complete. Smartling's Repository Connector default is all authorized strings in the file; requiring every string in the file, authorized or not, is a configuration change made through a Solutions Architect or Support. In the dashboard, the Fully Published Files download option applies the stricter rule across every job a file belongs to (Smartling Help Center, How to Download Translated Files).

Partial-translation delivery settings in Smartling: the reference figures

How do you configure a connector so partial translations never break the build?

The sequence below applies to a repository connector, a CMS connector, or a direct Files API integration.

1. Fix the delivery condition first — Decide whether the destination should receive a file only when it is complete for a locale (Smartling's COMPLETED trigger, or a GitHub Connector pull request on job completion) or on every change (ONCHANGE). Teams that merge translation pull requests without review should stay on completion-based delivery; teams with a review step in the pipeline can afford progress-based delivery.
2. Set the retrieval type to published — Use retrievalType=published in every production download so only strings that cleared the workflow are written to the destination. Reserve pending for a staging branch where reviewers want to see in-progress work, and pseudo for layout testing before translation starts.
3. Choose the fallback deliberately — Keep includeOriginalStrings at its default so untranslated keys carry the source text and the interface renders, or set it to false when the destination framework has its own locale fallback and an empty value is the signal it expects. Confirm the file type is one of the five the parameter supports before relying on it.
4. Define completion scope for files that span jobs — If a resource file is regularly extended after its first job, use the Fully Published Files option for manual downloads and ask Smartling to switch the Repository Connector to the all-strings condition, so a file is not delivered while a newer job still holds untranslated keys.
5. Listen for completion and re-delivery — Register callbacks for file-per-locale completion and job completion, or poll the recently published files endpoint, because translations can be corrected after the first delivery and the integration must pick up the updated file (Smartling Help Center, Tutorial: Translation Jobs and Workflows).

Configuring partial-translation behavior at the connector fits teams that...

• Ship resource files (JSON, Android XML, Java properties, Gettext, YAML) through a repository connector or the Files API and need the build to pass regardless of translation progress.
• Add new strings to existing files between releases, so a single file routinely spans more than one translation job.
• Translate into several locales that finish at different times and want each locale's file to arrive as soon as that locale is complete.
• Run a review or post-edit step and need a clear line between in-progress and Published translations in what gets delivered.
• Rely on the destination framework's own fallback logic and need control over whether a missing translation arrives as source text or as an empty value.

When the fallback setting is not the right place to solve the problem

• If the question is when a batch should go live across all locales, the answer is a Workflow Hold step or a connector publish state, covered on the batch translation publishing control page, not a download parameter.
• If translated files are re-uploading to Smartling as source files, the issue is the Repository Connector's pathRegex matching both source and translated paths, which no delivery setting fixes.
• If a CMS connector delivers entries rather than files, per-locale delivery on completion is already the behavior for connectors such as Contentful (Entries), and the fallback switch does not apply.
• If translations are corrected after launch, the fix is a callback or recently-published poll that triggers re-delivery, not a stricter completion rule.

Evaluation checklist: questions to ask a vendor about partially translated files

What does the connector write into a string that has no translation yet?
Ask for the exact behavior and the default. Smartling's default is the source-language string; an empty string is an explicit choice, and the switch works only for Gettext, Java properties, custom XML, Android XML, and JSON.

Can the connector wait to deliver until a file is fully translated for a locale?
Confirm this is the default, not an add-on. Smartling's Repository Connector defaults to COMPLETED, and the GitHub Connector delivers its pull request when the job completes.

How does the platform define fully translated: all strings in the file, or all strings that were authorized?
The two differ whenever some strings are excluded from a job. Smartling's Repository Connector uses all authorized strings by default and can be switched to all strings.

Does an in-progress translation ever appear in a production download?
Look for a retrieval-type control. With retrievalType=published, Smartling substitutes the source string for any translation still being edited or reviewed.

What happens when a file is extended after its first job completes?
Ask how the platform treats a file that belongs to several jobs. Smartling's Fully Published Files option downloads only files complete across all authorized jobs, up to 500 per download.

How does the integration learn that a delivered translation was later corrected?
Confirm callbacks fire per file per locale and per job, and that a recently-published endpoint exists for polling.

Can locales be mapped one-to-many between the platform and the repository?
Smartling's Repository Connector maps locales 1:1; similar locales such as es and es-ES are handled by creating both in Smartling and sharing translations through Cross-Country Leverage.

How Smartling handles partially translated files across its connectors

Smartling separates three decisions that other platforms often bundle: when a file is delivered, which translations qualify, and what fills the gaps. In the self-hosted Repository Connector for GitHub, GitLab, and Bitbucket, a downloadTranslations node in repo-connector.conf sets the trigger to COMPLETED (deliver only when all translations for the file are complete) or ONCHANGE (deliver whenever a translation changes), sets retrievalType to PUBLISHED, PENDING, or PSEUDO, and sets includeOriginalStrings to control whether an untranslated key carries the source text or an empty string for Gettext, Java properties, custom XML, Android XML, and JSON files. The default delivery condition is that all authorized strings in the file are Published for the locale, and the connector can be switched to require every string in the file through Smartling's Solutions Architects or Support.

The hosted GitHub Connector creates a translation branch and pull request when the job completes, containing one file per language, so a partially translated pull request only appears when Early Delivery is switched on for a pre-published pass. Direct integrations use the Files API, where the download endpoint accepts retrievalType values of pending, published, pseudo, and contextMatchingInstrumented; with published, translations still in editing or review are replaced by the source string, and the pre-published translations from a workflow step's Pre-publish setting are included. Callbacks fire when a file completes in a locale and when a job completes, and a recently published files endpoint lets an integration pick up translations corrected after the first download.

For teams downloading by hand, the Files tab of a project or job offers Current translations (in progress) or Published translations, and the job's Files tab adds Fully Published Files, which returns only files complete across every job they belong to, up to 500 translated files across all pages of the job. If a language is not fully published, a standard download still contains source copy in the untranslated positions, so a reviewer can open the file without hitting blanks. The same family of controls covers content connectors: file-based connectors such as Contentful (Entries) and Webflow deliver each locale once that locale is fully translated, and the WordPress plugin can download on Translation Completed or on Progress Changes, with a Pseudo retrieval type for layout checks.

Questions connexes

• How do you control when and how batches of translated content publish back to your CMS?
• What are the best GitHub localization tools for translating code repositories?
• What are the best headless CMS localization tools?