As noted in previous posts, we’ve been working over the past year to improve the Express documentation, based on broad input from the Express community. We’re continuing that effort, and today we’re happy to announce that in parallel we are adding professional translation of the documentation.
By now, you’ve heard that in September, IBM acquired StrongLoop, the corporate sponsor of the Express project. IBM has a great deal of expertise in localization and translation – after all, “international” is the first word in the company name! Accordingly, IBM will be providing the expertise to translate the Express documentation into the following languages:
- Brazilian Portuguese
- Simplified Chinese
- Traditional Chinese
Back in February we restructured the site to enable community translation into other languages. To date, we’ve accepted translation contributions in Spanish, Japanese, Russian, Chinese, Korean, and Portuguese. Most of the translations include the home page and a handful of Getting Started pages. The worldwide Express community has benefited from these community translations contributed by people from around the world, and we want to thank them all for their work.
We’d like to give a special shout-out to a small group of Brazilians who recently translated the entire Express documentation site into Portuguese: Gidenilson Alves Santiago (gidenilson), Rafael Dias (RafaDias), Thiago Rodrigues (trsouz), Alberto Souza (albertosouza), Alan Hoffmeister (alanhoff), Joel B. Santos (joelbars), Alan Leite (alanleite) [NOTE: handles are GitHub IDs]. We’ll continue to use their translation since it is so recent and complete, and we’ll be adding translation of a couple of new English pages.
We would also like to thank the following people for their translation contributions:
- Spanish – John F Triana (john1988triana), marimari (gurumelo)
- Japanese – Sakata Sinji (NKMR6194), Furuya (syuilo)
- Russian – Ivan Zmerzlyi (DangelZM)
- Chinese – Li Renhai (filow), Wang Sai (wangsai)
- Korean – SeongHoon Ryu (ryush00)
Apologies if we’ve inadvertently omitted anyone!
Unfortunately, it’s not easy to combine the existing community translations with the upcoming professional translations. That means in general, we’ll replace the existing community translations with the new translations, because they will be based on the latest English documentation.
It also means we won’t be able to accept further community translation in those languages. Why can’t we use both community and professional translation? It comes down to the tools and processes that professional translators use; they use a combination of machine and human translation and also a “translation memory bank”. The tools look up English sentences in the translation memory and automatically replaces them with the corresponding translated text.
With a professional globalization team working on the project, we expect to be able to keep the translations reasonably up-to-date with the English documentation. This is difficult with community translation, because translation is time-consuming, and the English source is constantly evolving.
Also, we’ll be very happy to accept translations into languages not in the list above. And, once we release the initial set of professional translations, we’ll ask for review comments via GitHub that we can pass on to the translators to update their translation memory. In general, we’ll be updating the translations on a regular basis as Express and the English documentation evolve.
Watch this space for an announcement of when the new translations are available on expressjs.com.
Contributing to Express documentation
Regardless of the ongoing translation, we’ll continue to improve and expand the English Express documentation. As always, we work in collaboration with the community in keeping with the nature of an open source project. You can make changes and additions to the documentation using the same basic process as for the code.
We have a rudimentary style guide you can review to understand our writing conventions. We’ll also be working to expand it in coming weeks to provide more guidance.
You can use a variety of workflows for doc contributions, but if you’re interested in a specific page on the site, process is really simple:
- Open the page of interest on the Express documentation site. For example, suppose you’re interested in making some changes to the “Hello world example” page: http://expressjs.com/starter/hello-world.html.
- Scroll to the bottom of page, and click the “Edit this page on GitHub” link to open the markdown source document for that page. For the “Hello World example” page, that’s: https://github.com/strongloop/expressjs.com/blob/gh-pages/starter/hello-world.md.
- To make an edit, click the “edit” button in GitHub, which will fork the project. Then you can use GitHub’s online editor and markdown previewer to make your changes right in your web browser. When you save your changes, GitHub will automatically make a new branch and open a pull request (PR) for your edits.
- Someone on the core team will review the PR, and either approve and merge it, make additional changes, or start a conversation about it in GitHub.
That’s pretty easy!
Of course, if you have more complex changes that span multiple pages, you can use the git command line and the process you prefer to open a pull request.