Feb 232007

One of my major goals for the Mozilla Developer Center going forward is to find ways to improve the process by which our documentation is translated into languages other than English. The key idea is to ensure that the largest number of programmers are covered by our documentation.

To accomplish this, we need to ensure that certain key languages have high-quality, well-maintained documentation that is kept current.

Our translators are doing a great job, but it’s time for us to find ways to bring a little order to the chaos and help ensure that all our translations (not to mention our English documentation) are kept in sync with each other.

I’ve jotted down some ideas and some notes and would like to get feedback from the other writers and translators. Let’s work together to find ways to make your work easier.

 Posted by at 7:30 PM

  9 Responses to “Making documentation translation better”

  1. I’m glad you mention the issue of tagging translated pages as requiring updates. When I correct errors (sometimes serious) in documents that have been translated, I’ve wondered if the corrections would ever reach the translations, how I could tell if they did, or whether there was anything I could do to encourage the correction to propagate. It would be great if having changes to translated documents propagate at a reasonable rate could be the norm.

  2. In the last year in portuguese mdc, I dedicated to the translation and organization of the pages structure and the help documentation. This year we have new contributors, and with this, great possibilities to follow the wikis with more updates and also to guarantee greater quality of the translations, as much in the part technique how much in the legibility.
    David, this is good, but with this the time of each edition also will be bigger. In my opinion the ideal would be a tool, if possible…

  3. I don’t see the great benefit in translating the documentation. I would assume that most programmers would know English. I remember, that some of the first English words I learned (to spell correctly) as a child was the keywords and function names for the languages I used (and I hope you are not considering translating the keywords or functions as Microsoft did in Office95(?) — that was painful). Personally I also try to stick with software in English since some translations aren’t very good and it might be hard to recognize a translated term perhaps because it’s translated to literal, but it is also more useful to search for error messages in English. But I speak as a native speaker of a quite small language, so natives of larger languages might not have the same need for English.

    I would suggest that one shouldn’t think of English (e.i. “en-US” just so we agree on the spelling) as “the language spoken in America”, but rather the pragmatic Esparanto.

    If you wanted to improve the DMO site, I would suggest trying to improve the perceived load time (e.g. combine and compress all the css and js files and put them on the server as flat files — some of them are generated at runtime by php-scripts and at times it takes 1 second, per file, consecutively). Right now DMO seems to me to be a slow site and I believe serving only/mostly pre-generated html-files would help alleviate that (and even if the site is a wiki, I wouldn’t think that the content changes that often).

    Another problem seems to be that the wiki style of the site encourages using prose instead of a more compact, easily skimable “tabular” writing style (e.g. I find the style of the http://msdn.microsoft.com/workshop/author/dhtml/reference/dhtml_reference_entry.asp reference better — although they do work hard to make it not work in mozilla and it is quite slow — than the DMO documents.

    Another way to improve the documentation would be to try to document some of the gotyas. As the MS docs have notes similar to (from memory) “This property is not part of any standard” or “This property is part of the W3C DOM level 1”, the mozilla docs could add “This property is part of XX standard, but is not widely supported” or “This property not part of any standard, but is supported by FF X, IE Y and Opera Z making it supported for 98% of web browsers on average (click to customize weights browser usage)”.

    (with regards to your site, (1) the horisontal lines in this textarea don’t scroll with the content, so their placement seem quite arbitrarily relative to the text (2) it seems confusing that the “Name (required)”, “E-mail (required, not displayed)” and “URI” labels are place underneath the text fields and (3) it also seems confusing that the line in the bottom of the text fields extends out under the pencil/envelope/globe icon.

  4. Eric,

    It seems to me that you pre-assumed that MDC documents are all
    1- technically correct, to begin with, and
    2- already up-to-date/updated

    and that is not true. What bugs me is that people can start translating a document which has not been completely edited, entirely tuned. This happened to me with http://developer.mozilla.org/en/docs/DOM:window.open and
    Today, the French version is not updated but the English version is pretty much updated.


  5. Well, that’s the idea to this work we’re starting on now — to find ways to ensure that the documentation gets kept up to date across all translations.

    As to whether or not translations are necessary at all, that’s an interesting question, and one I’d like to hear more comments on from non-native English speaking developers.

    I doubt that all programmers speak English, and there’s also the issue of whether or not their English is good enough to fully comprehend complex technical documentation. Perhaps it’s usually the case, but we do want to ensure that our documents reach the broadest possible audience.

  6. Hi.
    I’ve made a presentation in the mozilla devroom at the fosdem about “Mozilla Localisation status report”.
    And a part of this presentation is about the localisation of MDC.
    You can find it in pdf on my website :


    The big issues in localising MDC is maintaining pages you already have localised (find when and how much the original page has changed) and find witch one to localise first.

  7. The asumption that developers know English is just as wrong as the one that all people in the word know enough English to use an English-only browser (after all, a browser is mainly icons). People want things in their language, I know people with 1 or 2 doctorates that can barely read English. I read and write English quite fluently but I prefer to read in my language. If translations were unnecessary, you could find computer books in English on the shelves, I can believe that in smaller countries like the Netherlands or Norway this could be the case because the target market for translated comouter books would be too small to be profitable for publishers, but I have never seen a computing book in English in my country.

    If, as a developper, I have to choose between XAML and XUL for a project for instance, I will go to the one with the best documentation and part of the value of this documentation is the language used. If I have to study documentation for a longer time because it’s not in my language, I am wasting my time and for professional developers, that’s money.

    Besides, the MDC does not only host translated documents but also some documents directly written in French/Polish/German… (and which would be localized to English BTW).

    There is a big XUL community in France, contrary to most countries. And the real big difference with other languages is that most of xulplanet has been translated for a long time while other languages have to rely on the original site only.

  8. I’ve done some looking around and don’t see any extensions or options in MediaWiki that let you inform others if an article changes in another language. This makes me wonder if perhaps we could make use of the ability to have emails sent on changes, and set up a bot of some kind that would process the “article changed” messages to automatically let the translators for that article know when there’ve been changes.

  9. Pascal, I agree with you; I think we need to have translated documentation — and it’s also true that having the ability to get documentation translated back to English from other languages would be helpful too, and right now we’re not at all set up to do that. I’m going to continue to look into ways to improve our ability to find articles that need translating or updating.