Skip to content

PEP 545: Update language tag guidelines #5000

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
m-aciek wants to merge 2 commits into
base: main
Choose a base branch
from
+20 −10
Open

PEP 545: Update language tag guidelines #5000

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c58ac6
Update language tag guidelines in PEP 545
m-aciek Jun 19, 2026
49141e0
Fix backticks in PEP 545 language subtag description
m-aciek Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 20 additions & 10 deletions peps/pep-0545.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,15 +187,25 @@ Language Tag
''''''''''''

A common notation for language tags is the :rfc:`IETF Language Tag <5646>`
[4]_ based on ISO 639, although gettext uses ISO 639 tags with
underscores (ex: ``pt_BR``) instead of dashes to join tags [5]_
(ex: ``pt-BR``). Examples of IETF Language Tags: ``fr`` (French),
``ja`` (Japanese), ``pt-BR`` (Orthographic formulation of 1943 -
Official in Brazil).
[4]_ (BCP 47, RFC 5646), which is based on ISO 639 for language codes,
ISO 15924 for script codes, and ISO 3166 for region codes. Gettext uses
ISO 639 tags with underscores (e.g. ``pt_BR``), but IETF tags use hyphens
as separators instead of dashes to join tags [5]_ (e.g. ``pt-BR``).

It is more common to see dashes instead of underscores in URLs [6]_,
so we should use IETF language tags, even if sphinx uses gettext
internally: URLs are not meant to leak the underlying implementation.
Examples of IETF Language Tags:

* ``fr`` (French),
* ``ja`` (Japanese),
* ``pt-br`` (Portugese as spoken in Brazil),
* ``pa-guru`` (Punjabi written in Gurmukhi script)

The ``script`` subtag is used when a language can be written in multiple
writing systems. For example, Punjabi can be written in Gurmukhi (``pa-guru``)
or Shahmukhi (``pa-arab``).

It is more common to see hyphens instead of underscores in URLs [6]_,
so we should use IETF language tags in URL paths, even if Sphinx or Gettext use
different internal conventions. URLs should not leak implementation details.

It's uncommon to see capitalized letters in URLs, and docs.python.org
doesn't use any, so it may hurt readability by attracting the eye on it,
Expand All @@ -206,10 +216,10 @@ states that tags are not case sensitive. As the RFC allows lower case,
and it enhances readability, we should use lowercased tags like
``pt-br``.

We may drop the region subtag when it does not add distinguishing
We may drop the subtag when it does not add distinguishing
information, for example: "de-DE" or "fr-FR". (Although it might
make sense, respectively meaning "German as spoken in Germany"
and "French as spoken in France"). But when the region subtag
and "French as spoken in France"). But when the subtag
actually adds information, for example "pt-BR" or "Portuguese as
spoken in Brazil", it should be kept.

Expand Down
Loading