Flask Docs Translation

Contributing Guide

Installation

• Click the "Fork" button to fork this repository on GitHub.
• Clone your fork repository locally (replace {username} with your username):

$ git clone https://github.com/{username}/flask-docs-<UPDATE THIS>
$ cd flask-docs-<UPDATE THIS>
$ git remote add upstream https://github.com/<UPDATE THIS>/flask-docs-<UPDATE THIS>

• Create a virtual environment and install requirements:

For Linux/macOS:

$ python3 -m venv env
$ source env/bin/activate
$ python -m pip install --upgrade pip setuptools
$ pip install -r requirements/dev.txt
$ pip install -e .
$ pre-commit install

For Windows:

> python -m venv env
> env\Scripts\activate
> python -m pip install --upgrade pip setuptools
> pip install -r .\requirements\dev.txt
> pip install -e .
> pre-commit install

Self-Assignment

• Open <https://github.com//flask-docs-/edit/main/README.md>.
• Find the "Translation To-do List" section, mark the chapter you want to translate in following format:

- [ ] example @your_username Your Name

You can link the username to your GitHub profile:

- [ ] example [@your_username](https://github.com/your_username) Your Name

• Leave a commit message (e.g., "Assign example to @your_username"), then click the "Propose changes" button to create a PR.

Recommended Translation software

As explained below, translations are done using .po files. One good editor is POEdit (not to be confused with POEditor)

Translation

• When the self-assignment PR is merged, create a new branch locally (be sure to update the example branch name, for example, translate-cli):

$ git fetch upstream
$ git checkout -b your-branch-name upstream/main

• Translate the .po file in the docs/locales/<LANG>/LC_MESSAGES directory.

An example of one such file, from docs/.../index.po, is given below.

#: ../../index.rst:4
msgid "Welcome to Flask"
msgstr "<FILL HERE BY TARGET LANGUAGE>"

Another case, msgid is multi-line text and contains reStructuredText syntax:

#: ../../index.rst:11
msgid ""
"Welcome to Flask's documentation. Get started with :doc:`installation` "
"and then get an overview with the :doc:`quickstart`."
msgstr ""
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE :doc:`installation` "
"FILL HERE BY TARGET LANGUAGE :doc:`quickstart`."

Please be careful not to break reST notation. Most po-editors will help you with that.

• Mark the chapter as finished (fill the checkbox with "x"):

- [x] example @your_username Your Name

• If you are the first translator, update the FIRST AUTHOR <EMAIL@ADDRESS> comment at the top of the .po file.
• Update the Last-Translator field value at the top of the .po file.
• Commit the changes:

$ git add docs/locales/<LANG>/LC_MESSAGES/example.po README.md
$ git commit -m "Translate docs/example"

• Build the docs and preview the changes:

For Linux/macOS:

$ cd docs
$ make html

For Windows:

> cd docs
> .\make.bat html

Open {project_location}/docs/_build/html/index.html in your browser to view the docs.

• If everything is working as expected, push the changes to GitHub:

$ git push origin your-branch-name

• Open the home page of your forked repository, you will see a notice about the new branch. Click the "Compare & pull request" button to create a PR.
• The translation coordinator will review your PR very soon. Thank you!

Translation To-do List

Be sure only mark one chapter at a time, mark another one when the former PR is created. Unless it's a long chapter, we may reset the assignment if you doesn't finish the translation in ten days.

docs/

• advanced_foreword (reserved)
• appcontext
• async-await
• becomingbig
• blueprints
• changes
• cli
• config
• contributing
• debugging
• design
• errorhandling
• extensiondev
• extensions
• foreword (reserved)
• htmlfaq
• index (reserved)
• installation (reserved)
• logging
• quickstart (reserved)
• reqcontext
• security
• server
• shell
• signals
• templating
• testing
• views

docs/tutorial/ (reserved)

• blog
• database
• deploy
• factory
• index
• install
• layout
• next
• static
• templates
• tests
• views

docs/deploying/

• asgi
• cgi
• fastcgi
• index
• mod_wsgi
• uwsgi
• wsgi-standalone

docs/patterns/

• appdispatch
• appfactories
• caching
• celery
• deferredcallbacks
• distribute
• fabric
• favicon
• fileuploads
• flashing
• index
• jquery
• lazyloading
• methodoverrides
• mongoengine
• packages
• requestchecksum
• singlepageapplications
• sqlalchemy
• sqlite3
• streaming
• subclassing
• templateinheritance
• urlprocessors
• viewdecorators
• wtforms

docs/api

• L0~L1000
• L1000~L1500
• L1500~L2000
• L2000~L2500
• L2500~L3000
• L3000~L3500
• L3500~L4000
• L4000~L4500
• L4500~L5000
• L5000~L5500
• L5500~L6000
• L6000~L6500