¡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//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
• Explorations for a notification form between documentation and Rosetta sites
• 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/ 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 be the repository owner. 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/. Further information at 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/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. workspace (e.g., #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/. 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.

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, @nullbyte, @milana_cap, @otto, @clorith, @kenshino, @coachbirgit, @femkreations for the review, proofreading and hours spent on this proposal.

#docs, #documentation, #i18n, #l10n