Title: documentation – WordPress.org Project

---

#  Tag Archives: documentation

 [  ](https://profiles.wordpress.org/javiercasares/) [Javier Casares](https://profiles.wordpress.org/javiercasares/)
4:18 pm _on_ September 6, 2023     
Tags: docs, docs-de, documentation, i18n, l10n

# 󠀁[Proposal: Documentation translation / localization](https://make.wordpress.org/project/2023/09/06/documentation-translation-localization/)󠁿

_¡Hola!_ WordPress features an extensive array of documentation, but it’s primarily
available in English and distributed across multiple platforms. This poses a significant
challenge, as over half of WordPress installations globally are in languages other
than English. Consequently, many users cannot easily access documentation in their
native tongue. So, how can we address this issue?

## Current Status

The bulk of WordPress documentation resides on two primary websites: wordpress.orgWordPress.
org The community site where WordPress code is created and shared by the users. 
This is where you can download the source code for WordPress core, plugins and themes
as well as the central location for community conversations and organization. [https://wordpress.org/](https://wordpress.org/)/
documentation and developer.wordpress.org. While there are additional resources 
like manuals, tutorials, and forums, these two websites serve as the cornerstone
for end-users, advanced users, and developers alike.

While some sections have been translated into other languages, the vast majority
of this valuable content remains English-exclusive.

## Final Objective

Given that over half of all WordPress installations are in languages other than 
English, our goal is to translate and sustainably maintain all the documentation
in the world’s primary languages, with room for future expansion.

In the initial phase, we will focus on translating documentation tailored for end-
users, advanced users, and developers. Subsequent stages will include additional
resources such as Learn WordPress, Team Handbooks, and other related materials.

## Previous discussions on the topic

 * [Future plans for HelpHub](https://make.wordpress.org/docs/2023/02/07/future-plans-for-helphub/)
 * [Explorations for a notification form between documentation and Rosetta sites](https://make.wordpress.org/polyglots/2023/05/03/explorations-for-a-notification-form-between-documentation-and-rosetta-sites/)
 * [Discussion for a proposal for WP.org content translation and localization](https://make.wordpress.org/polyglots/2023/08/15/discussion-for-a-proposal-for-wp-org-content-translation-and-localization/)

## Implementation Strategy

The method of achieving this monumental task is the proverbial million-dollar question.
It has undergone extensive consideration, collaboration, and refinement across all
involved teams. While it may not be the perfect plan, it is the most viable one 
we have arrived at after four iterative cycles of improvement.

Acknowledging that there are ongoing developments within the WordPress ecosystem,
such as GutenbergGutenberg The Gutenberg project is the new Editor Interface for
WordPress. The editor improves the process and experience of creating new content,
making writing rich content much simpler. It uses ‘blocks’ to add richness rather
than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/)
Phase 3 and Phase 4. Although we’ve considered these, incorporating them at this
stage is not feasible.

This proposal offers a realistic pathway to making WordPress documentation accessible
to a global audience.

## Centralizing Documentation Creation

The initial step in our strategy is to consolidate all documentation into a single,
easily accessible location. Currently, the creation and discussion of documentation
are scattered across various platforms such as Google Docs, GitHubGitHub GitHub 
is a website that offers online implementation of git repositories that can easily
be shared, copied and modified by other developers. Public repositories are free
to host, private repositories require a paid subscription. GitHub introduced the
concept of the ‘pull request’ where code changes done in branches by contributors
can be reviewed and discussed before being merged by the repository owner. [https://github.com/](https://github.com/),
and WordPress itself.

To simplify maintenance and access, we have decided to host the foundational documentation
on GitHub. Each segment of documentation will have its own dedicated repository,
enabling individual teams to work in a more organized and efficient manner. This
structure will also facilitate separate issue tracking and discussions for each 
repository, while allowing cross-repository conversation through project links.

## Language-Specific Organization

To accommodate translations, each repository will feature folders named after the
ISO codes of the languages into which the documentation will be translated. Initially,
these folders will include “en” for English, and subsequently extend to other languages
like “de” for German, “es” for Spanish, “fr” for French, and “it” for Italian.

## Teams and Notifications

To stay abreast of changes in documentation, we’ll establish three tiers of teams
that mirror the existing structure of the Polyglots community.

1. **Repository Maintainers**: These individuals will be responsible for the overall
functionality of each repository. They will manage other teams and ensure that any
updates are correctly implemented.

2. **General Translation Editors (GTEGeneral Translation Editor General Translation
Editor – One of the polyglots team leads in a geographic region [https://make.wordpress.org/polyglots/teams/](https://make.wordpress.org/polyglots/teams/).
Further information at [https://make.wordpress.org/polyglots/handbook/glossary/#general-translation-editor](https://make.wordpress.org/polyglots/handbook/glossary/#general-translation-editor))**:
GTEs will oversee each language-specific documentation group. Their role involves
validating translations and ensuring their accuracy. There will be as many GTEs 
as there are languages to translate.

3. **Translators**: These contributors will carry out the actual translation work
from one language to another.

When a change is made to any piece of documentation, the translators will receive
notifications to update their translations accordingly. Should any language have
pending translations, the respective managers will be alerted for validation and
approval.

Those charged with high-level maintenance of the documentation will also keep track
of the synchronization configurations between GitHub and WordPress, ensuring a seamless
workflow and timely updates.

## Translation Strategy

GlotPress, the WordPress built-in translation system, will not be used in this initiative
to allow greater flexibility to adapt translations. The use of Machine Translation
or Translation Memory will be at the discretion of the translators.

Given our scalability objectives, we’re focusing initially on translating into “
general” language variants rather than “localized” ones. For example, we won’t distinguish
between “Spanish from Spain” and “Spanish from Mexico,” or between “French from 
France” and “French from Canada.” Instead, our target is to cover the main languages
spoken across all WordPress installations, with approximate percentage distributions
as follows:

 * `DE` – German (6%)
 * `EN` – English (48%)
 * `ES` – Spanish (7%)
 * `FR` – French (5%)
 * `IT` – Italian (4%)
 * `JA` – Japanese (6%)
 * `PT` – Portuguese (5%)
 * `RU` – Russian (3%)

This coverage would extend to over 80% of existing WordPress installations.

Management for each translation team will occur through dedicated channels in the
Global SlackSlack Slack is a Collaborative Group Chat Platform [https://slack.com/](https://slack.com/).
The WordPress community has its own Slack Channel at [https://make.wordpress.org/chat/](https://make.wordpress.org/chat/)
workspace (e.g., [#docs-de](https://make.wordpress.org/project/tag/docs-de/)). These
channels will allow contributors worldwide to collaborate effectively. We’ll also
establish translation guidelines for each language to ensure the text aligns with
cultural norms and linguistic nuances, whether formal or informal.

## Content Structure and Format

All documents will be stored in Markdown format, compatible with GitHub’s native
editing capabilities. This ensures a user-friendly interface accessible via a web
browser, although more advanced GitGit Git is a free and open source distributed
version control system designed to handle everything from small to very large projects
with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning
fast performance. Most modern plugin and theme development is being done with this
version control system. [https://git-scm.com/](https://git-scm.com/) users are free
to use the tools they prefer for translation work.

Each document will feature an initial H1 headerHeader The header of your site is
typically the first thing people will experience. The masthead or header art located
across the top of your page is part of the look and feel of your website. It can
influence a visitor’s opinion about your content and you/ your organization’s brand.
It may also look different on different screen sizes. (or “#” in Markdown) that 
designates the document title, followed by a final H2 header (or “##” in Markdown)
labeled “Changelog” to log major updates transparently.

The information architecture will mirror the URLURL A specific web address of a 
website or web page on the Internet, such as a website’s URL www.wordpress.org structure:
language-specific folders will be followed by root files, which will contain an `
index.md` and any additional folders or subfolders needed for organizing the content.
This approach enables the use of localized URLs for each language, further enhancing
accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to 
the design of products, devices, services, or environments for people with disabilities.
The concept of accessible design ensures both “direct access” (i.e. unassisted) 
and “indirect access” meaning compatibility with a person’s assistive technology(
for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility).

### Publication Process

The final decision to publish documentation will rest with the maintainers of each
respective project. Maintainers will have access to a configuration file, often 
referred to as a “manifest,” where they can list the Markdown files hosted on GitHub
along with corresponding WordPress slugs, content architecture, and priority ranking
for menu arrangement.

Furthermore, the manifest will specify the unique slugs, URLs, or identifiers for
different languages. This enables a seamless transition between language versions,
allowing users to switch easily from one to another. Once content is integrated 
into this manifest, it will automatically be converted from Markdown to HTMLHTML
HTML is an acronym for Hyper Text Markup Language. It is a markup language that 
is used in the development of web pages and websites. or the relevant blockBlock
Block is the abstract term used to describe units of markup that, composed together,
form the content or layout of a webpage using the WordPress editor. The idea combines
concepts of what in the past may have achieved with shortcodes, custom HTML, and
embed discovery into a single consistent API and user experience. format.

![](https://make.wordpress.org/project/files/2023/09/Translation-System2-1008x1024.
jpg)

## The power of the global community

One of the revolutionary aspects of this system is its capacity to enable content
creation directly in languages other than English. While this introduces a layer
of complexity requiring coordination, it opens up new avenues for content generation.
A contributor who may not be proficient in English but is fluent in French, Spanish,
or Italian can now create original content.

In this way, the system empowers the community to produce content in a non-English
language first, which can then be translated into English. This democratizes the
content creation process and harnesses the talents of over half of WordPress users
worldwide who are non-English speakers.

## Challenges Ahead

While this proposal paints an optimistic picture, the implementation is far from
simple. Numerous elements, including content management, translation coordination,
technology interfaces, and overall project management, contribute to the intricacy
of this initiative.

However, many of these challenges have already been anticipated, and others will
undoubtedly emerge as the project progresses. One promising aspect is that once 
we successfully translate one repository, the subsequent translations should unfold
more smoothly, given that the coreCore Core is the set of software required to run
WordPress. The Core Development Team builds WordPress. process remains consistent
across all elements.

In essence, this initiative is an ambitious undertaking, but its scalability and
adaptability make it a worthy challenge, promising significant benefits for the 
global WordPress community.

## Just the Beginning: A Unified Vision for WordPress Documentation

As initially mentioned, WordPress documentation exists in a myriad of locations 
and formats. This project serves as a foundational step toward standardizing tools
and practices. It aims to create a centralized repository where everyone knows where
to find information, can trace the history of changes, and receives due credit for
their contributions in both creating and translating content.

But the initiative goes beyond mere standardization. WordPress has a rich ecosystem
that includes an expansive Lean WordPress site, replete with numerous manuals, tutorials,
and community-driven projects. Each Make Team within the community has its body 
of documentation, offering insights into how our community operates. This is invaluable
information that could benefit a wider audience, particularly those who may be deterred
from participating because they lack proficiency in English.

As our community continues to grow, open and inclusive communication becomes increasingly
vital. This initiative not only promotes that growth but also democratizes access
to information. In doing so, it makes it possible for a more diverse range of individuals
to engage with the community in meaningful ways, even in teams where language has
previously been a barrier.

Thanks to [@estelaris](https://profiles.wordpress.org/estelaris/), [@nullbyte](https://profiles.wordpress.org/nullbyte/),
[@milana_cap](https://profiles.wordpress.org/milana_cap/), [@otto](https://profiles.wordpress.org/otto/),
[@clorith](https://profiles.wordpress.org/clorith/), [@kenshino](https://profiles.wordpress.org/kenshino/),
[@coachbirgit](https://profiles.wordpress.org/coachbirgit/), [@femkreations](https://profiles.wordpress.org/femkreations/)
for the review, proofreading and hours spent on this proposal.

[#docs](https://make.wordpress.org/project/tag/docs/), [#documentation](https://make.wordpress.org/project/tag/documentation/),
[#i18n](https://make.wordpress.org/project/tag/i18n/), [#l10n](https://make.wordpress.org/project/tag/l10n/)

 * [Login to Reply](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fmake.wordpress.org%2Fproject%2F2023%2F09%2F06%2Fdocumentation-translation-localization%2F%23respond&locale=en_US)