Issue Details (XML | Word | Printable)

Key: MBS-1406
Type: New Feature New Feature
Status: Open Open
Priority: Normal Normal
Assignee: Ian McEwen
Reporter: Nicolás Tamargo
Votes: 3
Watchers: 3
Operations

If you were logged in you would be able to see more operations.
MusicBrainz Server

Devise a way to allow translation of documentation

Created: 02/Feb/11 12:43 PM   Updated: 21/Feb/13 06:31 AM
Component/s: Documentation, Internationalization
Affects Version/s: None
Fix Version/s: Unscheduled

Issue Links:
Duplicate
 


 Description  « Hide

Import of http://bugs.musicbrainz.org/ticket/849

Currently, there's no way of translating and displaying MusicBrainz's documentation. This is more useful a start than localizing the page itself (although that could be nice too), as it seems non-fluent English speakers have little problem using the site itself. They do have lots of trouble reading the guidelines, though.



Sort Order: Ascending order - Click to sort in descending order
nikki added a comment - 06/May/12 01:20 AM

One idea I had while talking on IRC a few days ago:

1. Decide where to store translations in the wiki, e.g. /DE:Page_Name
2. When a user with the interface set to 'de' loads /doc/Page_Name, look for /DE:Page_Name.
3. If it's found, show the translated page, with a message saying something like "This is a translated version of [insert link to English version]".
4. If it's not found, show the English page, with a message saying something like "We do not have this page in [insert language]. Here is the English version instead."
5. On other versions of the page, show a message saying something like "This is the [language] version of this page. The [interface language] version is [insert link]."

/doc/ would need to support a query parameter, e.g. ?lang=en, or some other way of forcing it to load English in order for the link in #3 to work. I would also prefer Page_Name to load DE:Page_Name without changing the URL. That way the URLs are easy to share with people regardless of the language they're using MB in.

I think that approach would make it possible to translate pages without having to worry about lots of broken links (if you link to the same language versions) or having to update all the links that point to a page (if you link to the English versions). It would mean though that you would need to use /doc/ to efficiently browse the documentation in another language. We might need to make it easier to switch from the wiki to /doc/.

I don't know we would make sure the translations stay up to date, nor how we would alert people to the fact a page needs updating.




Oliver Charles added a comment - 11/Jun/12 08:42 PM

Ian McEwen added a comment - 19/Feb/13 12:59 AM

Adapting from nikki's proposal, I did some thinking on the bus today, and I think my plan is this:

a.) translated pages go on the wiki at Page_Name/lc(LANG)optional(_uc(COUNTRY)) This avoids any weirdness about namespaces.
b.) translated pages will have a designated template on them which points to their related English version. We'll call this Template:i18n-translated for now.
c.) pages that have been translated will have a template on them which points to all available translated versions. We'll call this Template:i18n-original for now.

Given these things, the server will:
a.) support a query parameter to override the language setting
b.) given a language in the appropriate format (from the parameter or otherwise), it will do:

if lang != 'en':
    try page/lang; use if found
    otherwise, if lang has a country code, try page/base(lang), where base(lang) is the language sans country code; use if found
if no page has been chosen yet, try the untranslated page, use if found, otherwise error as expected

given a page to use:
    if lang != 'en' and the page is in english: add a banner noting that a version in the language of choice couldn't be found, so it's using english
    if lang != 'en' and the page *is* translated: add a banner noting that the english version (providing a link, using the fancy query parameter) is canonical
    if the language is set by the query parameter: display a banner to unset the query parameter

Banners that get added, except the one for unsetting the query parameter, will attempt to insert themselves into the i18n wiki-templates (using classes added by the templates – and with extensive commenting in the templates to avoid accidental vandalism!). Notably, the templates themselves should include the untranslated versions of the banners (for a slightly degraded, but still providing the relevant information, experience on the wiki proper), and the server should replace these with their appropriate translated representation. By this mechanism the translation of short strings surrounding documentation can be part of the usual .po files, and the only translation that translators need to do on the wiki is long-form text translation.
c.) In order to provide canonical URLs, when someone requests a translated documentation page directly (e.g. navigates to /doc/Style/de, rather than the automatic request of that page via Style with lang=de) the server should look at the contents of the page, determine (from the i18n-translated template) that this is a translation, and issue a redirect to e.g. /doc/Style?lang=de.
d.) When the language query parameter is on a doc URL, it should also be on all internal links within the page (this can happen in our existing rewriting to /doc/).

For translators, this is fairly easy:
a.) translate a page
b.) add or update the i18n-translated template pointing to the original page
c.) add or update the i18n-original template on the original page
d.) pester someone to transclude as appropriate

Finally, for pages where an exact translation is important (i.e., style pages), some extra bits will be needed when a new guideline passes:
a.) add an "out of date" flag on each relevant language in both the i18n-original and i18n-translated templates. These links will display differently (from the english to the language versions) and include an extra warning in the banner about English's canonicalization (on the translated page itself).

Everyone (but nikki and reo especially): what do you think of this method?


Ian McEwen added a comment - 21/Feb/13 06:31 AM

nikki and I talked about this, and she proposed a bit more server-side stuff for tracking out-of-dateness. Specifically: don't bother, with pages that aren't transcluded. For pages that are: additionally transclude the translated page, but when transcluding have the server keep track of what the current version of the untranslated page is. This way, when the original page is later updated, the server can detect that the version numbers (between the pointer for the translated page, and the transclusion entry for the untranslated page) don't match, and display a banner appropriately.