NLS additions to I18N chapter of developers-handbook [Was: Re: svn commit: r189765 - in head: . lib/libc lib/libc/nls]

[Gábor Kövesdán]

>> I've spent some time on writing a short section on this trying to do 
>> this from a practical viewpoint. Please take a look ant tell me what 
>> do you think: 
>> http://kovesdan.org/files/developers-handbook/posix-nls.html
>
> s/are usual text files/are normal text files/?
ATM, we have "common text files". Rene sent some corrections, but I 
haven't yet updated the patch.
>
> I'm a bit surprised there isn't an include file that magically does 
> this for you?
>
>   extern nl_catd           catalog;
>
>   extern char             *nlsstr[];
No, I'm afraid there isn't. Think of using multiple catalogs from one 
application. You need to refer to them with an identifier when you call 
catgets(). The example I included in the documentation is a simplified 
one, it uses one catalog with one set. It satisfied usual needs, though. 
I don't think one would use more catalogs from an application very 
often, but the opportunity is given. I can't think of a really good 
example, but for example, let's suppose we have a localized gzip, which 
handles NLS and we are working on bzip2. There might be messages in 
gzip's catalog file, which we would reuse, e.g. "error in archive file" 
or such general ones. It would reduce duplicated messages but would make 
bzip2's localization partly depend on gzip. Or maybe we could collect 
the common messages to a single catalog file and besides, create gzip's 
and bzip2's own catalog with further messages. Well, it was just a silly 
example, but things like this is possible with NLS.
>
> Is it expected that this same programming approach will work for 
> applications to be compiled on other platforms, such as Mac OS X, 
> Solaris, and Linux?  (I see the word POSIX, but that has various 
> meanings :-).  In particular, suppose I want to update OpenBSM to use 
> catalogs -- it contains both libraries and binaries -- will I need to 
> do anything special?
Sincerely speaking, I haven't tried it. I can make a test app, which 
prints out a single message depending on LC_MESSAGES and I can test it 
on Linux, but unfortunately I don't have Mac OS X, nor Solaris access.
>
> Do you have any advice on what to do for libraries that provide error 
> strings in their own error spaces?  Is it intended that the library's 
> init and destroy functions will open and close catalogues?  Will this 
> work if the application the library is used by doesn't know about 
> catalogues?  Etc...
It will work. Actually, this is the case of libc. For example, ls(1) 
doesn't have to know about catalog, but this just works out of the box:

 > env LC_MESSAGES=es_ES.ISO8859-1 ls nonexistingdirectory
ls: nonexistingdirectory: Fichero o directorio inexistente

I haven't looked at ls's code but obviously it calls err(1, NULL), which 
checks errno and prints this related error message, which is defined in 
libc's catalog file. The catalog must be initialized before using it but 
as for the closing I think you can just omit it without any real harm, 
because the file will be released when the app terminates. Calling 
catclose is more important if you explicitly want to release the 
resource, because you know you won't need it any more or if you want to 
reuse the variable to open another catalog.
>
> In the bsd.nls.mk section, there's no worked example, which I think 
> would be helpful.
Good point, I'll add an example there, as well.
>
> You begin by saying "Beyond the basic I18N functions" -- is there an 
> introduction section that talks about those functions as well?
No, unfortunately. I meant there wchar-cleannes, respecting LC_TIME and 
such cases... E.g. sort has a -M option which tells sort to sort by 
month abbreviations. A localized sort should take those from LC_TIME 
instead of just using wired-in "JAN", "FEB", ... strings. I think it 
would be a long-term goal to extend developers-handbook. As for I18N, 
I'll try to add more content on a step-by-step basis.
>
> Is there a comprehensive project to identify opportunities for using 
> catalogues through the system that need owners?  This sounds like it 
> might be a useful GSoC project if someone can impose some structure on 
> it?
No, there's no organized project. I got interested in I18N a long ago, 
translating docs to Hungarian and then I realized there are nifty 
opportunities to extend language support beyond translated docs. Now it 
seems I'll apply to SoC with a project that delivers a BSDL libiconv, 
which is also very demanded. I'm doing preliminary research and 
discussing the details with my potential mentor. As for NLS as a SoC 
project, I'm not sure if it's enough for that. We have a good 
infrastructure for NLS (POSIX.1-compliant libraries and bsd.nls.mk) and 
adding catalog support to individual utilities might be too 
"mechanical". I mean, you just need to insert my code snippet and 
collect the strings into a template that translators can use and it just 
works. As you wrote, libraries might be more complex, but I don't know 
about any crucial difference that applies to libraries.
Thanks for your interest in this effort,

-- 
Gabor Kovesdan
FreeBSD Volunteer

EMAIL: gabor at FreeBSD.org .:|:. gabor at kovesdan.org
WEB:   http://people.FreeBSD.org/~gabor .:|:. http://kovesdan.org