Software Center documentation

David Planella david.planella at
Fri Mar 5 11:40:17 UTC 2010

Hi all,

El dv 05 de 03 de 2010 a les 08:17 +0000, en/na Matthew East va
> However, I proposed this last September and one of the objections was
> that the help file is licensed under the GPL. If that can change, then
> I think this would be a good idea. Here is a link to the discussion.

Ah, thanks for the link Matthew, I had not been aware of the previous

> Obviously the absence of translations for this help file is extremely
> unfortunate.

Sorry, I should have explained better. Michael already set up the help
file for translations. We were just not exposing it in Ubuntu until the
question whether to integrate it with Ubuntu docs had been addressed.

El dv 05 de 03 de 2010 a les 09:06 +0000, en/na Matthew Paul Thomas va
> Help me understand the reasons given in that discussion:
> >       * Translations would be more visible to translators, as they'd be
> >         in the Ubuntu templates list at
> Why wouldn't the software-center templates be in the templates list at 
> Does this mean the rest of 
> software-center is currently untranslatable? If so, how should we fix 
> that?

Right, I'm afraid that was again me not being too clear on the
explanation. Let me give some background and expand on that before

We are talking about the translations of the software-center
documentation here, the UI has been translatable since its creation.

== Documentation translations ==

In general, due to Launchpad's support for gettext but not for
documentation formats, the translatable documentation always needs to

      * Converted to gettext to be imported into Launchpad and thus
        exposed to translators. This is an automated step which can be
        taken care of in the build system of the package
      * Converted back to translated XML from the files exported from
        Launchpad in gettext format. This needs to be done to ship the
        translations to users, and it is a semi-manual process, in which
        the maintainer needs to request an export of the translations,
        commit them in the sources and generally run a conversion
        script. That's the tricky part with documentation translations.

== UI translations ==

This is in contrast to the translations of an application's UI. These
are in general already in Gettext format, and the process is fully
automated: translations and templates are imported upon package upload,
and are shipped in language packs without the need for the maintainer to
do anything.

== Source package space / Project space ==

There is another point to clarify here: an application and its
translations can live in two places in Launchpad:

      * Project space: that's the upstream project in Launchpad
        (, and the corresponding
        location for translations
        ( That
        actually permits some more automation in handling translations:
        automatic imports and exports can be enabled to get templates
        exposed in Launchpad and translations committed automatically.
        The drawback here is visibility. Ubuntu translators do not
        usually work in the upstream packages: there are too many, not
        grouped in a central location.
      * Source package space: that's the Ubuntu source package at and
        the corresponding location for translations at The advantages of having a project's translations here is that they have got much more visibility, since the source packages is where Ubuntu Translators generally work: all the apps they need to translate are available at This is great for UI translations, as they are automatically taken care of by language packs, but not for documentation, where as explained above, the maintainer needs to manually export translations, build and release them.

== Other issues ==

Manual work: I'll just reinstate this again. There is manual work
involved in fetching and converting the translations. While there are
developers which know about translations and consistently ensure that
they are correctly built and included in the packages (Michael being one
of them), this is in my experience not always the case, and manual steps
are always a point of failure. This is not to complain about developers:
the process should be automated, but we do not have that infrastructure
right now and we rely on the ubuntu-docs team instead.

LiveCD space: if translations are included in the package, it will
contain translations for _all_ languages. While this is not a problem
for most users, it becomes more critical when we are talking of the
LiveCD and space constraints. A solution might be to have a separate
'software-center-doc' package containing the original documentation and
all translations, or 'software-center-doc-$LANG' packages, one for each

My point was simply, that until there is a solution for these issues,
the best approach would be to let the Ubuntu Docs team handle the
translations of documentation by integrating them in ubuntu-docs, as
their experience and track record guarantee that translations will be
exported by NonLaguagePackTranslationDeadline [1] and correctly shipped.

If the current license does not make that possible, I would at least
want everyone involved to be aware of the tradeoffs in each of the
approaches, and make sure that translations for Software Center
documentation in Lucid are in shape.

I would also be happy to organize a session to discuss this on the next

So now, to answer the questions:

* Why wouldn't the software-center templates be in the templates list at
- They can be in the source package space, I just thought they'd be in
the upstream project space at When I first wrote
that, I hadn't seen that the source package had been prepared to
generate a translation template. That template can be imported in the
source package space, and thus exposed in

* Does this mean the rest of software-center is currently
untranslatable? If so, how should we fix that?
- The software-center UI is currently translatable and has been since
the beginning. There is no need to fix that.

> >       * They'd be shipped as part of ubuntu-docs, and integrated in the
> >         package's workflow (i.e. translations would be built before
> >         NonLanguagePackDeadline)
> Why wouldn't translations for software-center help pages be built at 
> the same time as translations for the rest of software-center?

For the reasons stated above: due to the need to convert documentation
to gettext to make it translatable, there is a manual step involved: the
maintainer needs to fetch translations of the documentation by a given
deadline and build them. They cannot currently be included in language

UI translations are built automatically by langpack-o-matic when
creating the language packs, without the need of maintainer

> >       * This will make it possible to ship only the translations in the
> >         user's locale (as opposed to all translations). Now ubuntu-docs
> >         are part of language packs.
> Is ubuntu-docs the only package covered by language packs? If any other 
> packages are covered, how does that work?

Only the UI translations are covered by language packs. Due to Launchpad
not supporting xml as a translatable format, we do not allow translating
documentation of imported upstream projects in Ubuntu (that's why the
GNOME documentation or man pages are not translatable in Launchpad, for

The only exception is ubuntu-docs, where we have a bit of a trick: when
the package is uploaded, Launchpad now allows importing the translated
xml files and exporting them as they are in language packs. That is,
they pass through Launchpad transparently, but we can still ship
translations separately in language packs only containing the
translations of a given language. The reason for doing that was saving
space in the LiveCD and to ship only translations for the languages
included in the CD.

> >       * It would be consistent with what other Ubuntu applications do
> >         at the moment with documentation (e.g. usb-creator)
> Does that mean if you uninstall usb-creator, help pages remain on your 
> computer discussing it as if it's still there?

Someone from the docs team might better answer this one, but I believe
yes, uninstalling usb-creator will not uninstall its help pages.

> > I agree that from a translations and documentation team point of view,
> > this would be better, for the reasons which you have listed.
> >
> > However, I proposed this last September and one of the objections was
> > that the help file is licensed under the GPL. If that can change, then
> > I think this would be a good idea. Here is a link to the discussion.
> >
> >
> As I said in that discussion, the reason for the GPL is that "it is 
> quite likely in future versions that some of the help will be embedded 
> in the code, and vice versa". I hope the same becomes true for the help 
> in every Ubuntu application, because that seems like the primary way to 
> get people to read it.
> > There is one other point which I would raise though: as I understand
> > it, Software Center is something of an upstream project, because it is
> > used in distributions like Debian. If that's the case, then there is a
> > clear argument for having help as part of the application which can be
> > used by Debian.
> Yes, here it is in Debian:
> > Obviously the absence of translations for this help file is extremely
> > unfortunate. And if the decision is taken to keep it in the upstream
> > product, I would say that some serious effort should be put into
> > making it translatable in the same way as the application's interface
> > is.
> > ...
> What else do we need to do to make it translatable?

Nothing else, as mentioned above, it is already :)

I hope I could help in clarifying the questions.



David Planella
Ubuntu Translations Coordinator

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: Aix? ?s una part d'un missatge signada digitalment
URL: <>

More information about the ubuntu-doc mailing list