This document is currently in the proposal stage and has not been formally adopted.

Besides code, the community often contributes and maintains other text in comments and other documents.  This document intends to describe how we provide optional versions of these documents for folks who prefer non-US English writing.

Good-faith efforts at contributing and modifying text by non-native speakers generally should not be vetoed.  Instead, native speakers are encouraged to thank them and simply make corrections.

Discussions of proper use of US English, and what choice of words are most effective can often be controversial.  If you think some words should be changed, first consider how important it is, then start a discussion before making changes.  Very few, if any, changes of this sort must be made before releasing.  It is generally better to publish it and get feedback from the wider community.

Text appears in many places:

1) Release package documents:  README, RELEASE_NOTES, LICENSE, NOTICE,
CONTRIBUTING, etc.
2) API names (classes, properties, styles, etc)
3) ASDoc and JavaDoc comments (really, any comments that end up in user
documentation)
4) Written user documentation
5) Website
6) Wiki
7) Error messages in the tools
8) Text in the SDKs and Applications we release that show up in some user interface.
The proposal is:
1) Release package documents will be written in US English but try to
avoid words that have different spellings or meanings in Int’l English.
Interested community members can post translated copies of READMEs and
RELEASE_NOTES (but not the others like LICENSE and NOTICE) on our wiki.
This is true for any language, not just Internationall English.  The wiki copies
will have to start with a disclaimer that they might be out-of-date.  The
first sentence under the title in README and RELEASE_NOTES will point to
the wiki and also warn that copies there may be out-of-date.  Any
translated copy that falls more than one release behind will be hidden.
The reason for not bundling translated versions is to avoid bottlenecks in
releasing if translators are not readily available
2) API Names will use US English spellings, especially since the W3C is
already using “color”.
3) ASDoc and JavaDoc comments will use US English.  Interested community
members are welcome to build translated copies of the generated docs.  We
will not hide stale copies as I think the ASDoc is more obvious about
which version it is for and folks will figure it out.  Proposals to reduce
the overhead of tracking changes in order to update the translated copies
are welcome after this proposal is approved.
4, 5) Any written user documentation and website materials will hopefully
have translated copies in as many languages as possible.  If we can’t
figure out how to auto-redirect based on browser locale, you will land on
US English and the US English version and the main flex.a.o page and a few
other popular pages will mention that there are other versions available.
There is no “master” version.  The versions can all be improved upon
without requiring synchronizing with other language versions.
6) The wiki pages can be in any language.  When modifying a page, use the
language that is already there.  Interested wiki authors are welcome to
provide translated copies of the wiki pages.
7, 8)  All of these strings should be in locales.
The overall principle is that things in 1, 2 and 3 all end up in a release
package.  Because the official Apache LICENSE uses US English, it will
appear more consistent to have all of the other things in the package use
US English.  But we should point folks to other translated versions if
they exist.
  • No labels