Internationalization

Readme.so is built with internationalization support, allowing users from around the world to create README files in their preferred language.

Supported Languages

Readme.so currently supports multiple languages through its internationalization system powered by next-i18next.

Section Template Languages

The following languages have complete section template libraries (defined in the data/ directory):

English

Code: en / en_ENFile: section-templates-en_EN.jsStatus: Primary language with all 33 section templates

中文简体 (Chinese Simplified)

Code: cn / cn_CNFile: section-templates-cn_CN.jsStatus: Full template library

Português (Portuguese)

Code: pt / pt_BRFile: section-templates-pt_BR.jsStatus: Full template library (Brazilian Portuguese)

Türkçe (Turkish)

Code: tr / tr_TRFile: section-templates-tr_TR.jsStatus: Full template library

UI Translation Languages

The user interface supports even more languages through the language dropdown (LanguageDropDown.js:3-84):

European Languages

English (/en)
Français - French (/fr)
Español - Spanish (/es)
Italiano - Italian (/it)
Deutsch - German (/de)
Nederlands - Dutch (/nl)
Русский - Russian (/ru)

Asian Languages

中文简体 - Chinese Simplified (/cn)
日本語 - Japanese (/ja)
한국어 - Korean (if supported)
हिंदी - Hindi (/hi)
বাংলা - Bengali (/bn)
తెలుగు - Telugu (/tl)

Other Languages

العربية - Arabic (/ar)
Türkçe - Turkish (/tr)
Filipino (/fil)
Bahasa Indonesia - Indonesian (/id)
Swahili (/sw)
O’zbekcha - Uzbek (/uz)
Português - Portuguese (/pt)

Some languages may have UI translations without complete section template libraries. The application will fall back to English templates when necessary.

Changing Language

Users can change their language preference using the language selector in the navigation area.

Find Language Selector

Look for the globe/language icon in the navigation area

Click to Open Dropdown

Click the icon to reveal the language selection menu

Select Your Language

Choose your preferred language from the dropdown list

Page Reloads

The page automatically navigates to the selected language route (e.g., /en, /cn, /pt)

Language Routes

Each language has its own route path:

https://readme.so/en    → English
https://readme.so/cn    → Chinese (Simplified)
https://readme.so/pt    → Portuguese
https://readme.so/tr    → Turkish
https://readme.so/es    → Spanish
https://readme.so/fr    → French
https://readme.so/ja    → Japanese
...and more

Bookmark your preferred language URL to always start in that language.

How Internationalization Works

Readme.so uses a multi-layer internationalization system combining section templates and UI translations.

Section Templates

Section templates are organized by language in the data directory:

// From data/index.js
import { tr_TR } from './section-templates-tr_TR'
import { en_EN } from './section-templates-en_EN'
import { pt_BR } from './section-templates-pt_BR'
import { cn_CN } from './section-templates-cn_CN'

export default {
  tr: tr_TR,
  en: en_EN,
  pt: pt_BR,
  cn: cn_CN,
}

Each template file contains:

All 33 section templates
Translated section names
Localized markdown content
Language-appropriate examples

Example: Chinese Section Template

// From section-templates-cn_CN.js
{
  slug: 'installation',
  name: '安装',  // "Installation" in Chinese
  markdown: `
## 安装

使用 npm 安装项目

\`\`\`bash
  npm install my-project
  cd my-project
\`\`\`
  `,
}

UI Translations

The user interface text (buttons, labels, messages) is translated using next-i18next:

// Example from EditorColumn.js
const { t } = useTranslation('editor')

// Translation keys like:
t('editor-select')           // "Select a section on the left to edit"
t('editor-column-editor')    // "Editor"
t('preview-column-preview')  // "Preview"

Translation files are typically stored in:

public/locales/en/ - English translations
public/locales/cn/ - Chinese translations
public/locales/pt/ - Portuguese translations
public/locales/tr/ - Turkish translations

Configuration

The i18n system is configured in next-i18next.config.js:

module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'cn', 'pt', 'tr', /* other locales */],
  },
}

Section Content Localization

When you switch languages, the section templates change to match:

English
Portuguese
Turkish

Section Name: “Installation”Content:

## Installation

Install my-project with npm

\`\`\`bash
  npm install my-project
  cd my-project
\`\`\`

Section Name: “Instalação”Content:

## Instalação

Instale my-project com npm

\`\`\`bash
  npm install my-project
  cd my-project
\`\`\`

Section Name: “Kurulum”Content:

## Kurulum

my-project'i npm ile kurun

\`\`\`bash
  npm install my-project
  cd my-project
\`\`\`

Switching languages affects:

Section template names
Pre-filled markdown content
UI labels and buttons
Help text and messages

It does NOT affect:

Your custom edits to sections
Custom sections you’ve created
Your section selection and order

Mixing Languages

You can create multilingual READMEs by editing the templates:

Creating a Bilingual README

Start in Your Primary Language

Select your main language (e.g., English)

Add Sections

Add the sections you need

Edit Content

Add content in your primary language

Add Translations

Edit sections to include translations below the primary content

Example: Bilingual Title Section

# My Awesome Project

A tool for managing development workflows and team collaboration

---

# 我的很棒的项目

用于管理开发工作流程和团队协作的工具

---

## Features / 功能特点

- Easy setup / 简单设置
- Fast performance / 快速性能
- Cross-platform / 跨平台

Contributing Translations

Readme.so welcomes contributions for new language support.

Translation Components

To add a new language, you need to provide:

Section Template Structure

Each language’s section template file should follow this structure:

export const [locale_CODE] = [
  {
    slug: 'section-slug',
    name: 'Translated Section Name',
    markdown: `
# Translated Markdown Content

Localized example text...
    `,
  },
  // ... more sections
]

Keep the slug values consistent across languages. The slug should always be in English (e.g., 'installation', not 'instalação') to ensure proper section matching and storage.

Translation Guidelines

When translating section templates:

Keep Technical Terms: Some terms like “npm”, “git”, “API” should remain in English
Localize Examples: Use culturally relevant examples and placeholder text
Maintain Formatting: Keep markdown structure identical to English version
Test Thoroughly: Ensure all 33 sections are translated and working
Update UI Strings: Translate all button labels, messages, and help text

Language-Specific Features

Some sections adapt to language and cultural contexts:

Authors Section

The Authors section includes locale-appropriate social media examples:

English
Chinese

## Authors

- [@katherine_peterson](https://www.github.com/katherine_peterson)

## 作者

- [@zhang_wei](https://www.github.com/zhang_wei)
- [微博](https://weibo.com/username)

Support Section

Contact methods may vary by language and region:

English
Other Languages

## Support

For support, email [email protected] or join our Slack channel.

Right-to-Left (RTL) Support

For languages like Arabic that read right-to-left:

Arabic (/ar) is included in the language dropdown. RTL layout support depends on the CSS implementation and may vary. The markdown content itself will render correctly on GitHub, which has built-in RTL support.

Reporting Translation Issues

If you find translation errors or missing translations:

Check Current Translation

Verify the issue in the current language

Visit Language Dropdown

Click the language selector and find the “Report translation error” link at the bottom

Open GitHub Issue

The link takes you to: https://github.com/koushikromel/readme-so-community/issues/new

Describe the Issue

Provide:

Language code
Section or UI element affected
Current text
Suggested correction

Best Practices for Multilingual READMEs

When creating READMEs for international audiences:

Start with English

English is the most widely understood language in the developer community

Add Key Sections in Other Languages

Translate at minimum: title, description, installation, and usage

Use Clear Section Dividers

Separate language sections with horizontal rules (---)

Be Consistent

If you translate one section, translate all or clearly mark which are translated

Recommended Structure

# Project Title (English)

English description

[English content...]

---

# Título del Proyecto (Español)

Descripción en español

[Spanish content...]

---

# 项目标题 (中文)

中文描述

[Chinese content...]

This approach ensures all users can find content in their language while maintaining a clear structure.

Get Started

User Guide

For Developers

Resources

Internationalization

Supported Languages

Section Template Languages

English

中文简体 (Chinese Simplified)

Português (Portuguese)

Türkçe (Turkish)

UI Translation Languages

Changing Language

Language Routes

How Internationalization Works

Section Templates

UI Translations

Configuration

Section Content Localization

Mixing Languages

Creating a Bilingual README

Contributing Translations

Translation Components

Section Template Structure

Translation Guidelines

Language-Specific Features

Authors Section

Support Section

Right-to-Left (RTL) Support

Reporting Translation Issues

Best Practices for Multilingual READMEs

Start with English

Add Key Sections in Other Languages

Use Clear Section Dividers

Be Consistent

Recommended Structure

Build docs developers (and LLMs) love

Get Started

User Guide

For Developers

Resources

​Supported Languages

​Section Template Languages

English

中文简体 (Chinese Simplified)

Português (Portuguese)

Türkçe (Turkish)

​UI Translation Languages

​Changing Language

​Language Dropdown

​Language Routes

​How Internationalization Works

​Section Templates

​UI Translations

​Configuration

​Section Content Localization

​Mixing Languages

​Creating a Bilingual README

​Contributing Translations

​Translation Components

​Section Template Structure

​Translation Guidelines

​Language-Specific Features

​Authors Section

​Support Section

​Right-to-Left (RTL) Support

​Reporting Translation Issues

​Best Practices for Multilingual READMEs

Start with English

Add Key Sections in Other Languages

Use Clear Section Dividers

Be Consistent

​Recommended Structure

Build docs developers (and LLMs) love

Supported Languages

Section Template Languages

UI Translation Languages

Changing Language

Language Dropdown

Language Routes

How Internationalization Works

Section Templates

UI Translations

Configuration

Section Content Localization

Mixing Languages

Creating a Bilingual README

Contributing Translations

Translation Components

Section Template Structure

Translation Guidelines

Language-Specific Features

Authors Section

Support Section

Right-to-Left (RTL) Support

Reporting Translation Issues

Best Practices for Multilingual READMEs

Recommended Structure