[Libvir] RFC: Add a short doc with libvirt coding style guidelines

[Daniel P. Berrange]

On Tue, Jan 15, 2008 at 03:49:32PM +0100, Jim Meyering wrote:
> "Richard W.M. Jones" <rjones at redhat.com> wrote:
> 
> > Daniel P. Berrange wrote:
> >> There's a few coding style guidelines we've kind of informally agreed upon
> >> wrt to libvirt patches, and perhaps more that we ought to make decisions on.
> >> For the benefit of people sending patches I reckon its worth writing these
> >> down. So I'm attaching a proposed doc 'HACKING' in which we can detail the
> >> guidelines.  And yes, we don't uniformly comply with these guidelines in
> >> all places....all the more reason to list them & fix cases where we don't
> >> comply :-)
> >
> >   5. Ensure any user visible strings are marked for translation
> >
> >       eg wrap all strings with _(...)
> >
> >         virXendError(xend, VIR_ERR_INTERNAL_ERROR,
> >                      _("domain information incomplete, missing domid"));
> >
> > Translating error messages is a bad idea: (1) Naive users ignore error
> > messages anyway. (2) It makes the error message much less useful when
> > doing an internet search for solutions. (3) If an error message is
> > posted to this list, it's much less useful if it isn't in English.
> 
> Hi Rich,
> 
> I've always heard that support for translatable diagnostics
> is an important feature.
> 
> While I'm no UI/internationalization expert, I would have thought that
> less-savvy users would need the messages more than others.
> 
> If a user is taking the time to report a bug to an English-speaking list
> and to include a precise diagnostic, they're probably clueful enough to
> translate any such message for us.  At worst, since we have the .po
> files, we can look up the translation manually -- or just use an online
> translator.

If you look at glibc - all the strerror() stuff is translated, and we feed
that into our own error messages. So if we didn't translate our own, we'd
be giving users error messages which contain a mix of englissh and translated
stuff.  Our users have been very proactive about providing translations
for our existing error messages, which suggests the translations are indeed
important to them.

Dan.
-- 
|=- Red Hat, Engineering, Emerging Technologies, Boston.  +1 978 392 2496 -=|
|=-           Perl modules: http://search.cpan.org/~danberr/              -=|
|=-               Projects: http://freshmeat.net/~danielpb/               -=|
|=-  GnuPG: 7D3B9505   F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505  -=|