i18n matters ought to be properly documented

@David Planella
@Arne Götje
@Martin Pitt

Hi guys,

I subscribed you to this bug in the hope that you will review an i18n document I wrote, and give feedback.

http://bazaar.launchpad.net/~gunnarhj/ubuntu-docs/lang-support/view/head:/i18n/C/i18n.xml

Any kinds of comments are welcome, i.e. on contents and layout as well as language/spelling/grammar. Thought that this bug may be a suitable place to post your corrections/questions/whatever.

Hi Gunnar,

First of all, thanks a lot for your work on this, which is just awesome.

After having had a look at it, here's some feedback I hope you find useful:

* The ubuntu-docs package is aimed at topic-based user documentation, so I'm not too sure this is the right place for it, as it describes things as the LC_* variables, which are too advanced for general consumption. It might be worth adding the documentation to the language-selector package itself.

* The docs team (and other projects in general) don't work directly on XML. They rather create a document in a documentation format such as docbook, which allows them to output the documentation in many other formats, such as xml or pdf. IT also allows translating the content. I'd suggest to use docbook for the source document.

Thansk!

On 30 March 2011 15:16, David Planella <email address hidden> wrote:
> * The ubuntu-docs package is aimed at topic-based user documentation, so
> I'm not too sure this is the right place for it, as it describes things
> as the LC_* variables, which are too advanced for general consumption.
> It might be worth adding the documentation to the language-selector
> package itself.

On the basis of a quick review, I would tend to agree with David -
although the document looks very solid and the work done is very
impressive, the approach and level of detail is probably not
appropriate for desktop user help. I would prefer to have this sort of
document in the wiki, with more high level usage instructions kept for
the language-selector package and a link to that from the ubuntu-docs
package. The nuts and bolts of gettext don't need to be explained for
the vast majority of our users, they just need to know how to install
and change languages.

> * The docs team (and other projects in general) don't work directly on
> XML. They rather create a document in a documentation format such as
> docbook

That's ok - the document format looks ok. Docbook is a type of xml.

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

Thanks David and Matthew for your comments! To be honest, I'm a little surprised, since I did have a user documentation on the topic "i18n in Ubuntu" in mind when I wrote it, not just a language-selector manual. My concern was rather that you would miss things. ;-)

A couple of weeks ago I was about to review and update the i18n docs, since there have been some not unsignificant i18n changes in Natty. However, the only i18n related document I found was this outdated (language-selector isn't mentioned) page in the wiki:
https://help.ubuntu.com/community/Locale

Making software available in many languages is a key point in the Ubuntu philosophy:
http://www.ubuntu.com/project/about-ubuntu/our-philosophy

That's one good reason IMO to include i18n in the official documentation. Isn't it kind of weird that "Visual Effects" is covered in considerable detail under "Customizing Your Computer", while i18n isn't mentioned at all?

Of course, there is always room for discussing the level of detail. David questions the section on LC_* variables, and Matthew the section on the $LANGUAGE priority list. So let's take a closer look.

I uploaded the linked branches to my PPA:
https://launchpad.net/~gunnarhj/+archive/i18n-docs

Suggest that you install the packages, to see the document in its context. The next best option is to download the i18n.xml file and view it in the help browser:

yelp file:///full/path/to/i18n.xml

The document is divided into 5 pages:
1. Introduction
2. gettext Language Handling
3. Language Support
4. Login Screen
5. Advanced Format Settings

Page 1 and 4 are so short, so I don't comment on them now.

Page 3 consists of user guidance to the Language Support tool (i.e. language-selector). I'm proposing a "Help" button on the main language-selector window that takes you directly to page 3, so besides being the most central part of the i18n document, the third page serves as a context help page for language-selector.

I think that the widget in language-selector for setting language(s) motivates a simple description of the priority list feature. That's what page 2 is for. I'd say it's pretty far from "the nuts and bolts of gettext", Matthew. :-) There is also a link to page 2 from the comment on page 3 on the language setting widget.

Page 5 is there because of a limitation of the language-selector UI compared to corresponding UIs in some other operating systems. The word "advanced" in the title emphasizes that the page is not for everyone.

Btw, when I now look at page 5, I think it is too long. Think the variable list should be reduced to the 4 or 5 variables that it's most likely that people want to control individually.

I'd suppose that the vast majority of our users don't need language-selector or an i18n document. They just set a language at installation and that's it. The proposed document is not for them. It's for users who want to get a basic understanding of Ubuntu's i18n model, and be able to conveniently change the settings to match their preferences. And it may be useful to point at for people who work with bugs or answer questions.

Hi Gunnar,

Thanks for working on this!

We normally target the system help at non-technical end users. In general, these people only look at the help when they have a specific problem. Their aim, we assume, is to fix their problem as quickly as possible and get on with their work, so we don't like to make them read through a lot of text or learn lots of new concepts. These users typically won't understand the concept of environment variables, or even the terminal, so a topic on gettext would not be suitable for them without putting them through a lot of introductory material first (which we don't have). That's my argument for why the document you wrote wouldn't be suitable for direct inclusion in the system help.

It would, however, be very suitable for users who want to gain a better understanding of how the i18n infrastructure works (as you said). These people will tend to have more interest in learning concepts, and are likely to be more technically-adept. We normally recommend putting documents for these "technical" users on the Community Help Wiki at help.ubuntu.com.

More information on i18n (from a non-technical user's perspective) is needed in the system docs, however. The upstream GNOME desktop help is currently undergoing a massive overhaul, and I'm not sure we have enough suitable i18n material in there at the moment. Would you like to have a look at it and let me know what you think? You can see a recent build (work in progress) here : http://library.gnome.org/users/gnome-help/unstable/

Thanks,

Phil

I just had a look at Gunnar's XML document, and I think it's a great help for users who want to do finer customizations of their language settings. So this should by all means be included. I'm not really fussed whether this lives in language-selector or ubuntu-docs, that's merely an implementation detail. If Matthew and Phil think it doesn't fit in ubuntu-docs, then let's put it into language-selector. After all, much of the document describes the settings of l-s, so in its entirety it isn't a good fit for the upstream gnome-help either. To me it seems quite suitable as an app specific help file.

Thanks!

Hi again,

I moved the proposed document to language-selector, and updated the PPA.
https://launchpad.net/~gunnarhj/+archive/i18n-docs

I for one don't believe in targeting the least tech-savvy users only.
They don't need docs, they need hand-holding. OTOH, people who have used
various flavors of Linux for 15 years or so won't care about any user
docs either; they just open a terminal window and type the commands they
learned long ago. ;-)

I tried to identify things that are not clearly explained by the l-s
GUI, and type them down. I also tried to cover what people tend to
report bugs and ask questions about. One detail worth mentioning is that
the first thing people see is a link to the language-selector specific
page. It's intended to facilitate for those who seek explanations
directly related to the language-selector GUI.

Would suggest that the document is uploaded for Natty approximately as
is (btw, it is DocBook, David). Then let's give it a few weeks to
further consider the contents and suggest changes. I have not (yet)
prepared for translations of the help document, and it's intentional so
to not unnecessarily bother the translators with messages that may well
be altered or removed very soon. Hence I suggest that we provide an
English only help document in Natty, while making it possible to
translate it in time for Oneiric.

Btw, I think it would be nice if the help document could be fetched also
via the <F1> key, but have no idea how to do that.

Gunnar

On 2011-03-31 16:01, Phil Bull wrote:
> More information on i18n (from a non-technical user's perspective)
> is needed in the system docs,

Well, I'm contributing with a suggested link to "Language Support Help"
from "Customizing Your Computer" (config-desktop), assuming that the
latter document will be used also in Natty. ;-) See merge proposal.
Also assuming that the link, if approved, will make it in some way to
the Natty version of
https://help.ubuntu.com/10.10/config-desktop/C/index.html

> The upstream GNOME desktop help is currently undergoing a massive
> overhaul, and I'm not sure we have enough suitable i18n material in
> there at the moment. Would you like to have a look at it and let me
> know what you think? You can see a recent build (work in progress)
> here : http://library.gnome.org/users/gnome-help/unstable/

The only document I find is "yelp ghelp:gnome-help#session-language" or
http://library.gnome.org/users/gnome-help/unstable/session-language.html

I for one don't like the sentence:
"The easiest way to add support for different languages is at the time
of installing your system."

With my Ubuntu glasses on, I suggest that it's patched in Ubuntu to be
replaced with something along these lines:
- You can add support for different languages either at the time of
installing your system, or within a session using the <ulink type="help"
url="ghelp:language-selector#support-tool"><application>Language
Support</application> tool</ulink>.
(That link syntax doesn't work in gnome-help in Natty, but you get the
idea.)

Otherwise, even if GDM in Ubuntu has undergone some significant i18n
changes, the text would work for us.

Also without my Ubuntu glasses, the above sentence isn't very smart IMO.
I mean, how many users will read it before installing? And letting them
know afterwards that the easiest way to do something would have been at
installation can't reasonably serve any purpuse but annoying them...

Let's return to your saying that you're "not sure [you] have enough
suitable i18n material in there at the moment". Let me ask: Does GNOME
provide any i18n software besides what's in GDM? If not, I don't really
see what else should be said in the upstream gnome-help. If I understand
it correctly, the various distributions deal with i18n in different
ways, and if that's true, the i18n user help should be distribution
specific, shouldn't it? I agree with Martin that the document I propose
for language-selector wouldn't fit in gnome-help, even if we leave its
level of detail aside.

HTH
Gunnar

This bug was fixed in the package language-selector - 0.29

---------------
language-selector (0.29) natty; urgency=low

  [ Gunnar Hjalmarsson ]
  * help/C/language-selector.xml:
    - Addition of DocBook document with help about Ubuntu i18n handling
      in general and language-selector in particular (LP: #742857).
  * data/LanguageSelector.ui:
    - "Help" button added (LP: #742857).
    - Title of the main window changed to "Language Support", i.e.
      same as the name of the app/tool.
  * LanguageSelector/gtk/GtkLanguageSelector.py:
    - Modified code for setlocale() exception handling.
  * data/main-countries:
    - Changed the main country of English from GB to US. Not that the
      latter is more 'right' or something, but it may prevent failures
      in certain situations, since en_US locales are more widespread.

  [ Martin Pitt ]
  * data/pkg_depends: Add hunspell-sh.
 -- Gunnar Hjalmarsson <email address hidden> Wed, 06 Apr 2011 11:29:23 +0200

Thanks for sponsoring the language-selector branch, Martin!

The status for language-selector (ubuntu) was changed back to "In Progress", since the package should be completed with stuff for translating the document. I also suppose that this bug report may be a place to talk about changes of the document and keep co-ordinating the i18n docs between ubuntu-docs and language-selector.

ubuntu-docs merge proposal superseded, so it was deleted.

The Natty docs will be based on gnome-user-docs, which includes a short page about changing language. A link to the Language Support Help has been committed to lp:~ubuntu-core-doc/gnome-user-docs/natty-unity.

This bug was fixed in the package language-selector - 0.31

---------------
language-selector (0.31) natty; urgency=low

  * help/C/language-selector.xml: Tweaking of help document, LP: #742857
 -- Gunnar Hjalmarsson <email address hidden> Mon, 11 Apr 2011 07:24:00 +0200

Status back to "In Progress" (see comment #10)

One of the work items on https://blueprints.launchpad.net/ubuntu/+spec/desktop-o-clean-up-language-support was to prepare Language Support Help for being translated. However, since that item was decided upon at UDS-O (http://pad.ubuntu.com/uds-o-desktop-o-clean-up-language-support), it has been decided that the l-s UI will be replaced by the g-c-c UI for languages and locales during the 12.04 development circle, and the work item in the blueprint has been dropped.

I'm currently working on preventing that language/locale settings functionality is unintentionally dropped, even if a few new packages (accountsservice, g-c-c, lightdm, g-s-d) have become involved. Nevertheless, if we would have the help document be translated now, due to the planned switch to the g-c-c UI most of that work would still likely need to be redone a few months later. Consequently we'd better stick to an English only Language Support Help also in Oneiric.

Let's consider this bug report to have served its purpose.