How to Make README.md Multilingual
This is a multilingual README.md template for GitHub projects. It allows developers to provide documentation in multiple languages efficiently.
When creating my first GitHub project, I was introduced to the concept of README.md, an important file that illustrates and describes your entire project on GitHub. While working on this document, I wondered how to make it available in different languages, since projects can easily be viewed by users worldwide. In this article, learn how to make your project descriptions multilingual and why this is important for accessibility.
The simplest and most straightforward way to support multiple languages is to create separate README.md files for each language. Each file should follow the naming convention README.lang.md, where lang represents the language code (e.g., en for English, pt for Portuguese, es for Spanish). For example:
Create files like README.[LANG-CODE].md (e.g., README.pt-PT.md, README.es-ES.md).
- README.md (default)
- README.pt-PT.md (Portuguese)
- README.es-ES.md (Spanish)
In the main README (usually in English), you can provide links to translated versions:
(Choose your language below / Escolha o seu idioma abaixo / Elija su idioma abajo)
🌐 How to Use Multilingual READMEs -> Separate Files (Recommended) -> Link them in the main README.md (see example above).
Another approach is to keep all translations in a single README.md file. You can organize the content into sections, each dedicated to a specific language. This is useful for smaller projects or when translations are not extensive.
[English version of the README content]
[Versão em português do conteúdo do README]
[Versión en español del contenido del README]
For an advanced solution, you can use GitHub Actions or other automated scripts to detect a visitor's preferred language and display the corresponding README. This requires creating a script that updates the main README.md based on the selected language, though it is a more complex and less common option.
There are also i18n tools that help manage and automate translations for documentation files, including README.md. These tools can be integrated into your workflow to simplify maintaining multiple README versions in different languages.
Supporting multiple languages in your README.md is an investment that can make your project more inclusive and accessible. Choose the approach that best fits your project's size and needs, ensuring users from different regions can interact with it effectively.