Troubleshooting & FAQ

This page collects common problems and questions about using Localizeflow, along with suggested solutions.

If you are just getting started, read Getting started and How Localizeflow works first.

Installation and access issues

I cannot install the GitHub App on my organization

On GitHub organizations, installing the Localizeflow GitHub App requires organization owner permissions.

Solution

• Ask an org owner to install the app by following Install and manage the GitHub App.
• After installation, the owner can invite you from the Teams page in the Localizeflow sidebar.

The repository I want does not appear in Localizeflow

If you do not see a repository in the + Connect repositories list:

• The app may not have access to that repository in GitHub.
• The repository might be in a different account or organization than the one where the app was installed.

Solution

1. Check the Localizeflow GitHub App settings in GitHub.
2. Confirm that:
   • The app is installed on the correct account or organization.
   • The repository is included in the app’s allowed repositories.
3. Return to Localizeflow and try + Connect repositories again.

Translation pull requests are not appearing

I enabled automation, but no pull request was created

Possible reasons:

• There were no relevant changes in your source language files.
• Your include/exclude paths do not match any files.
• Automation is paused or disabled.

Solution

1. Verify that your translation configuration includes the folders you expect (for example docs/en/**, blog/en/**, or **/*.md).
2. Confirm that automation is enabled for the repository.
3. Make a small test change to a source file and push it to the configured branch.
4. Wait a short time and check if a translation pull request appears.

Only some files are being translated

If certain files are not included in translation pull requests:

• They might be excluded by your configuration.
• Their paths may not match any include pattern.

Solution

• Review your include and exclude patterns.
• Make sure the files you care about are explicitly covered by an include pattern and not accidentally excluded.

Static documentation issues

My static docs project already has translated folders (e.g. docs/ko)

Having old translation folders in place can cause Localizeflow to treat them as additional source content. This can result in duplicated translations or confusing diffs.

Solution

1. Before enabling automation, remove old or manually maintained translation folders such as:
   • docs/ko, docs/ja
   • blog/ko, blog/ja
   • i18n/* or similar output folders
2. Move your original content into language-specific source folders, for example:
   • docs/en/**
   • blog/en/**
3. Update your translation configuration to include these new source paths.

See Static documentation sites for more details.

Permissions and collaboration

My teammate cannot see our projects in Localizeflow

If a teammate cannot see repositories or settings you expect them to see:

• They may not have been invited to the correct Localizeflow workspace.
• They might not have access to the underlying GitHub repositories.

Solution

1. Go to the Teams page in Localizeflow and confirm they are a member of your workspace.
2. If not, invite them by email or share an invite link.
3. Ensure they also have appropriate permissions on the relevant GitHub repositories.

General questions

Can I pause translations temporarily?

Yes. You can disable or pause automation for a repository if you are making large structural changes or want to reduce noise. When automation is paused, Localizeflow stops creating new translation pull requests until you re-enable it.

What happens if I edit translations manually?

You can always edit translated files directly. Once those changes are merged, they become part of your repository history. Localizeflow focuses on keeping translations aligned with the current source content and does not overwrite your changes arbitrarily.

Do I need to change my deployment or CI/CD setup?

In most cases, no. Localizeflow works through GitHub branches and pull requests. As long as your CI/CD pipeline builds from your repository content, translated files generated by Localizeflow will be included automatically after you merge translation pull requests.

How does Localizeflow handle frontmatter?

Localizeflow intelligently handles frontmatter fields in your Markdown files:

• Translates: User-facing text like title, description, excerpt
• Preserves: Technical fields like slug, id, date, author, tags, order, section
• Adjusts paths: Image paths like image, cover, og_image are automatically updated to point to the correct locations from translated files

Example:

Original file (docs/en/getting-started.md):

---
title: Getting Started
description: Learn how to get started with our platform
slug: getting-started
section: introduction
order: 1
sidebar_position: 1
image: ../images/hero.png
date: 2024-01-15
author: john-doe
tags: [tutorial, beginner]
---

Translated file (docs/ko/getting-started.md):

---
title: 시작하기                                    # ← Translated
description: 우리 플랫폼 시작 방법 알아보기           # ← Translated
slug: getting-started                            # ← Preserved
section: introduction                            # ← Preserved
order: 1                                         # ← Preserved
sidebar_position: 1                              # ← Preserved
image: ../images/hero.png                        # ← Preserved (same depth)
date: 2024-01-15                                # ← Preserved
author: john-doe                                # ← Preserved
tags: [tutorial, beginner]                      # ← Preserved
---

This happens automatically—you don’t need to configure anything.

If you need custom frontmatter handling for specific fields, contact us and we can configure it for your project.

Where to go next

• Getting started – quick path to your first translation.
• Static documentation sites – guidance for Astro, Hugo, Docusaurus, and similar projects.