🌍 Internationalization (i100) with Read The Docs

Learn how to create internationalized documentation using Read The Docs. This tutorial shows how to manage international documentation for open source and enterprise documentation projects.

Why Add Multilingual Docs

Global technical documentation enables users around the world to consume your documentation in the viewer’s preferred language. This guide will show you how to make your documentation available in any language.

Localize your documentation to reach wider audiences.
Support translations for users around the world.

1. Project Setup

First, you'll need a configured read the docs instance to proceed with i18n setup.

                    
pip install sphinx-intl
                    make -f Makefile help
                    rtd init
                        -n mydocs
                        -r myrepo
                    
                        python3 -m sphinx.ext.intersphinx


                
                    For full project setup instructions, see the documentation Project Setup guide.
                

                2. Configure i18n
                
                    After setup, add .po files for each language into the doc/i18n directory with locale files for the translations. For example:
                
                /docs
    /locale
        
            de.po
            it-IT.po
            sv-SE.po
        

                
                    More on translation file formats
                

                3. Building Languages
                                    
                        rtd build
                            -l en,es,fr
                            -t po
                            -b locale
                            -o . docs
                    
                

                4. Deployment
                
                    Once your documentation has been translated, deploy your international version for public viewing.
                
                
                    Read docs deployment
                
                
                    
                        Use the Deploy
                        readthedoc -d deploy -t html
                    
                

                
                    
                        
                            Tip
                        
                        

                            Use PO editor to manage multiple language files.
                        
                    
                

                
                    You can see live i18n project examples across multiple languages.
                    See demo project
                

                Conclusion
                
                    In this guide, you learned how to set up internationalized documentation using Sphinx or mkdocs.
                
                                    
                        For more information, see the
                        
                            International support
                            Internationalization