Static documentation sites

Static documentation sites are a perfect match for Localizeflow because:

• Your content is already in Markdown – no extraction or conversion needed.
• GitHub manages everything – versions, reviews, and deployments stay in your existing workflow.
• Translations follow the same structure – docs/en/ becomes docs/ko/, predictably and automatically.

The core principle: Localizeflow always uses exactly one source tree. By convention, this is docs/en/. Everything else—translations, old i18n folders, mixed language files—must be removed or Localizeflow will misidentify what to translate.

This page explains how to prepare and structure static docs projects so that Localizeflow can translate them reliably.

What counts as a static documentation site?

You are likely working with a static docs project if:

• Your site is built with a framework such as Astro, Hugo, Docusaurus, or a similar static site generator.
• Most of your content lives in folders like docs/, content/, or blog/.
• Deployments are triggered from Git (for example via GitHub Actions or another CI).

In all of these cases, the same high-level practices apply.

Common scenarios where Localizeflow fails

Before setting up Localizeflow, check if your repository has any of these issues. These are the most common reasons why Localizeflow misidentifies source content:

❌ Scenario 1: Mixed languages directly under docs/

docs/
  getting-started.md          (English)
  getting-started.ko.md       (Korean)
  installation.md             (English)

Problem: Localizeflow cannot tell which files are source and which are translations.

Solution: Move all English files to docs/en/ and delete the Korean files (Localizeflow will recreate them).

❌ Scenario 2: Old translation folders left in place

docs/
  en/
    getting-started.md
  ko/
    getting-started.md        (old translation)
  ja/
    getting-started.md        (old translation)

Problem: Localizeflow may treat old translations as new source content, creating duplicate or conflicting translations.

Solution: You must delete docs/ko/ and docs/ja/ before connecting to Localizeflow.

❌ Scenario 3: English files mixed into translation folders

docs/
  en/
    getting-started.md
  ko/
    getting-started.md        (Korean)
    new-feature.md            (accidentally English)

Problem: Localizeflow expects docs/ko/ to contain only Korean content. English files here will confuse the system.

Solution: Move new-feature.md to docs/en/ and delete it from docs/ko/.

✅ What Localizeflow expects

A clean repository structure looks like this:

docs/
  en/
    getting-started.md
    installation.md
    configuration.md

That’s it. Localizeflow will create docs/ko/, docs/ja/, etc. for you through pull requests.

Clean up existing translations

Before you connect your static docs repository to Localizeflow, you must do a one-time cleanup of existing translation folders.

You must remove:

• Language-specific folders such as:
  • docs/ko, docs/ja
  • blog/ko, blog/ja
• Generated translation or i18n output such as:
  • i18n/*
  • Other build artifacts that contain translated copies of your content

Why this matters Localizeflow expects exactly one clean source language tree. If old translations are left in place, they will be mistaken for new source content and lead to duplicated or conflicting translations.

Normalize your source language folders

Next, organize your original content into clear language-specific folders.

A common and recommended pattern is:

• docs/en/** – English documentation
• blog/en/** – English blog posts or changelogs

If your project currently has content directly under docs/ or blog/, you can move it into docs/en/ and blog/en/.

Once this is done, Localizeflow will always use en as the source language tree and generate translations for other languages (such as ko, ja) based on it.

Your translated content will live in parallel folders:

• docs/ko/**
• blog/ko/**

The rule is simple: exactly one source tree, and Localizeflow manages all target trees through pull requests.

Connect the repository and configure translations

After cleanup and folder normalization:

1. Connect your repository in the Localizeflow dashboard.
2. Open the repository detail page and edit the translation configuration.
3. Set:
   • Source language (for example en).
   • Target branch (for example main).
   • Target languages (for example ko, ja).
   • Include paths that point at your docs and blog content, for example:
     • docs/en/**
     • blog/en/**

These settings tell Localizeflow exactly which files inside your static docs project should be translated.

What gets preserved during translation

Localizeflow preserves your document structure and technical elements:

• Frontmatter – YAML metadata at the top of files remains intact.
• Code blocks – Code examples are not translated (only surrounding text).
• Deep folder structures – Nested paths like docs/en/tutorials/getting-started/intro.md work perfectly. Localizeflow mirrors the exact structure in target languages.

What Localizeflow translates (and what it doesn’t)

Localizeflow automates the repetitive and time-consuming work of translating Markdown documentation files.

However, UI strings and site elements are not automatically translated by Localizeflow. These include:

• Hero section text (for example hero.en.json, hero.ko.json)
• Navigation and header menus
• Language selector dropdown
• Footer links and text
• Sidebar category names
• Component files (.astro, .tsx, .vue, etc.)

Why?

• UI string structures vary significantly between teams and projects.
• For UI translations, we recommend using JSON-based i18n files and translating them directly with AI tools, which is often faster and more flexible for your specific setup.

How to translate UI elements:

You can use an AI assistant to help translate your UI strings. For example:

“I have a hero.en.json file with the following content: [paste your JSON]. Please create hero.ko.json with Korean translations, keeping the same structure.”

Localizeflow focuses on what it does best: keeping your documentation content in sync across languages through automated pull requests.

Framework-specific i18n configuration

After Localizeflow creates translated files, you must configure your framework to recognize language routes like /en, /ko, etc.

Astro

Astro does not have built-in i18n routing. You need to configure it manually.

Minimal configuration example:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'ko', 'ja'],
    routing: {
      prefixDefaultLocale: false
    }
  }
});

Folder structure:

src/
  content/
    docs/
      en/
        getting-started.md
      ko/
        getting-started.md    (created by Localizeflow)

Your Astro pages can then use Astro.currentLocale to render the correct content.

Hugo

Hugo has native multi-language support.

Minimal configuration example:

# config.toml
defaultContentLanguage = "en"

[languages]
  [languages.en]
    contentDir = "content/en"
    languageName = "English"
    weight = 1

  [languages.ko]
    contentDir = "content/ko"
    languageName = "한국어"
    weight = 2

Folder structure:

content/
  en/
    getting-started.md
  ko/
    getting-started.md    (created by Localizeflow)

Hugo will automatically generate /en/getting-started/ and /ko/getting-started/ routes.

Docusaurus

Docusaurus has a built-in i18n plugin.

Minimal configuration example:

// docusaurus.config.js
module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'ko', 'ja'],
  },
};

Folder structure:

docs/
  en/
    getting-started.md
  ko/
    getting-started.md    (created by Localizeflow)

Docusaurus will automatically generate /en/getting-started and /ko/getting-started routes.