Localized Images (wasRe: ubuntu-docs Requirements?)

[Shaun McCance]

On Thu, 2010-01-21 at 09:24 -0500, Kyle Nitzsche wrote:
> Matthew East wrote:
> > Hi Kyle,
> >
> > On Thu, Jan 21, 2010 at 1:18 AM, Kyle Nitzsche
> >> Does mallard? A transition to mallard should be evaluated in light of
> >> this "requirement," whatever it is.
> >>     
> >
> > It certainly supports images
> > (http://projectmallard.org/about/learn/media.html), but no markup
> > language really supports localised images. It's the build system and
> > team processes that will define how images can be localised. Mallard
> > isn't a build system. I don't know how gnome-doc-utils currently deals
> > with the translation of screenshots but we can ask around. Given that
> > we don't currently do it, anything that can be added would be a bonus.
> >
> >   
> So, we agree images sometimes are a benefit and that the ubuntu-docs 
> build system may not currently support localized images. I'd propose 
> that implementing this should be a "requirement" for which 
> implementation plans can be formulated.
> 
> Please note that launchpad.net/doctemplate supports building docbook 
> with localized images in a very easy to use way:
>  * each content directory has an "images/" directory. Theses are the 
> default images.
>  * you can add localized images directories, for example: images-es (for 
> Spanish images). If you put an image in there, it is used in producing 
> the localized docbook instead of the default one.
> 
> Thus, it simply allows adding localized files and they are used. No need 
> to write image filenames in a build system file.

With gnome-doc-utils, each translation of a document is kept
under a separate subdirectory.  The original document is in
the "C" subdirectory.  Images and other stuff is kept in the
language subdirectories.  (We usually put them in a "figures"
subsubdirectory, but that's just Gnome common practice.)

Documents are translated with PO files.  We use xml2po to go
to and from PO files.  xml2po finds all references to images
in the document and inserts checksums of the files into the
PO files.  This allows translators to see when an image has
changed so they can update their translated image.

Images are listed in the DOC_FIGURES variable in Makefile.am.
They only have to be listed once for the document, not for
each translation.  gnome-doc-utils manages the translations,
and will link to source images for any missing translated
images during install.

Note that if DOC_FIGURES is unset, it will pick up all *.png
files in "figures".  So you don't have to list them all.  But
this is deprecated behavior that will be removed when I move
things to yelp-tools.  I know it sounds convenient, but crazy
stuff ends up in release tarballs when you do wildcards.

Note that this isn't limited to images.  The same mechanism
works for audio and video files as well.


-- 
Shaun McCance
http://syllogist.net/