Documentation

Initial Setup Required

Before using XLIFF Translator, you need to configure your Angular application for internationalization.

Go to Setup

Getting Started with XLIFF Translator

Selecting Repositories

After connecting to a Git provider:

GitHubNot Connected

To connect, generate a Personal Access Token with the following scopes:

  • repo
  • read:org

Get your token here: Settings > Developer settings > Personal access tokens > Tokens (classic) > Generate new token

Token
Enter your access token
GitHub provider configuration form
  1. Select a provider: Choose from GitHub, GitLab, or Bitbucket
  2. Configure access: Create and provide the appropriate tokens
  3. Save your configuration: Enter your token and save the connection

Github

Create a Personal Access Token with repo, and repo:org scopes.

GitLab

Create a Personal Access Token with api, read_repository, and write_repository scopes.

Bitbucket

Create an App Password with repository:read and repository:write permissions.

Repository Management

Selecting Repositories

After connecting to a Git provider:

Organization
Repository
Updated Apr 8, 2025
90 translation units detected
No translation available...
Repository selection with translation options
  1. Navigate to the provider's page where your repositories are listed
  2. Browse and select the repository containing your Angular project with XLIFF files
  3. Specify the branch to work with (default is usually the main branch)

Translation Options

Select Branch
main
Xliff Extension
xlf
TransUnit State
new
Proceeded TransUnit State
translated
Translation options configuration modal

Reviewing and Finalizing

Pull Request Review

After the translation process completes:

  1. Review the created pull request in your Git provider
  2. Check the translated content for accuracy
  3. Make any necessary adjustments directly in the XLIFF files
  4. Merge the pull request to update your main codebase with the translations

This workflow allows you to keep translations in your version control system and follow standard code review practices for translation updates.

Tips for Effective Translation

  • Run translations regularly as you develop to avoid large batches of untranslated content
  • Create a dedicated branch for translations to keep them separate from feature development
  • Ensure your source code has clear context for translation units to improve AI translation quality
  • Always review AI-generated translations, especially for critical user-facing content
  • Use specific file patterns to target translations for one language at a time

Additional Resources

Translation Workflow

Estimation

Before running a translation, you can estimate the scope and complexity of the task:

  1. Select the repository you want to work with
  2. Click on "Estimate" to analyze your XLIFF files
  3. Configure the estimate options:
    • Branch: Select the branch containing your XLIFF files
    • File Pattern: By default "xlf" to search all XLIFF files. Use specific patterns like "ru.xlf" to target only Russian files
    • Translation State: Choose which translation units to include (default is "new" to focus on untranslated content)
  4. Review the estimate results showing the number of translation units to process

Why Estimate?

The estimation process helps you understand:

  • The exact number of translation units that need processing
  • How many credits will be required (1 translation unit = 1 credit)
  • Approximate time required (each translation unit takes 10-20 seconds to process)

Important: Large translation projects with hundreds of translation units can take significant time. Plan accordingly.

Translation

Running an AI-powered translation is a separate process from estimation:

  1. Select the repository containing your XLIFF files
  2. Click on "Translate" to begin the process
  3. Configure the translation options:
    • Branch: Select the source branch
    • File Pattern: Specify which XLIFF files to translate
    • Translation State: Select which translation units to process (e.g., "new", "needs-translation")
    • Target State: Define the state to set for translated units (e.g., "translated", "final")
  4. Start the translation process

You'll be prompted with the translation options modal as shown earlier in the "Selecting Repositories" section.

Translation Process

During the translation process, XLIFF Translator:

  1. Clones your project repository
  2. Identifies XLIFF files matching your pattern
  3. Analyzes each translation unit and its context in the source code
  4. Sends translation instructions to the AI engine with relevant context
  5. Updates the XLIFF files with the translations
  6. Creates a pull request with the changes (if configured)