Getting started

Localizeflow automatically translates your documentation and opens pull requests whenever the source file changes. This guide shows you how to install the Localizeflow GitHub App, connect a repository, prepare your docs structure, and run your first automated translation.

Prerequisites

• GitHub account.
• Access to the GitHub organization or repository you want to translate.
• A Localizeflow account. You can create one using Sign in with GitHub in the next section.

---

Sign in and install the GitHub App

1. Visit localizeflow.com.

2. Select Start with free trial.

3. Select Sign in with GitHub.

4. Sign in with your GitHub account.

5. After logging in with GitHub, you’ll be redirected to Localizeflow’s account selection page. To create your account, install the Localizeflow GitHub App. Select Install in new account.

6. Choose the account where you want to install the Localizeflow GitHub App — your personal account or an organization you manage.

   Installing the Localizeflow GitHub App on a GitHub organization requires that you are an organization owner. If you are not an owner, share this page with an owner and ask them to complete the installation step for you.

7. Select the repositories you want Localizeflow to access, then choose Save.

8. You will be redirected to the Localizeflow home page.

---

Connect your repositories to Localizeflow

1. On the Localizeflow home page, select + Connect repositories.

2. Choose one of the installed repositories you want to connect and select Save.

3. Your connected repositories will now appear on both the Home page and the Repositories page.

---

Prepare your repository for translation

Before you start automatic translation, make sure your repository structure is ready. This helps Localizeflow detect your source language correctly and avoid translating outdated or duplicate content.

Case A – Typical open source repositories

If your repository is a typical open source project (application or library code with a few Markdown files such as README.md or CONTRIBUTING.md):

• If you already have manually maintained translated copies of your docs (for example README.ko.md or a docs/ja/ folder), remove those translations before you start using Localizeflow so your default language remains the single source of truth.
• Otherwise, you can usually proceed without any additional cleanup.
• Just make sure your default language content is consistent (for example, most documentation is in English).

Case B – Static documentation sites (Astro, Hugo, Docusaurus, etc.)

If your repository powers a documentation site or blog (for example Astro, Hugo, Docusaurus, or similar static site generators), we recommend a one-time cleanup:

1. Remove existing translated content

   • Delete existing locale folders such as:
     • docs/ko, docs/ja, blog/ko, blog/ja
     • i18n/* or other generated translation output folders
   • This prevents Localizeflow from treating old translations as new source files.

2. Normalize your source language folder structure

   • Move your original (source language) content into language-specific folders, for example:
     • docs/en/**
     • blog/en/**
   • Localizeflow will treat en as the source language and generate other languages (such as ko, ja) from this tree.

---

Start automatic translation

1. Select the repository you just connected.

2. On the repository detail page, select Edit at the bottom.

3. Configure your translation settings:

   Basic settings (required for all repositories):

   • Framework: Choose Generic Git repository for typical open-source projects, or Documentation site if you’re using Astro, Hugo, Docusaurus, or similar frameworks.
   • Source language: The language your content is written in (default: en).
   • Target languages: Select one or more languages you want to generate (for example ko, ja, fr).
   • Target branch: The branch where translation pull requests will be opened. If empty, your repository’s default branch will be used.

   Additional settings (only for Documentation site):

   If you selected Documentation site, you’ll also need to configure:

   • Translation groups: Define source and output folder mappings. For example:
     • Source root: src/content/docs/en → Output root: src/content/docs/
     • Source root: src/content/blog/en → Output root: src/content/blog/

   Select Save.

   Generic Git repository is the simplest option—just select your languages and you’re done. Use this for typical repositories with files like README.md, CONTRIBUTING.md, or docs/*.md at the root or in simple folders.

   Documentation site requires translation groups to map your source language folder (e.g., docs/en) to the parent output folder (e.g., docs/). Localizeflow will then create docs/ko, docs/ja, etc. alongside your English content.

   See Translation configuration reference for all available options.

4. Select Start & Automate. Localizeflow will now automatically translate your documentation and open pull requests whenever the source changes.