Dev Week -- Integrating your package with Launchpad Translations -- dpm -- Thu, Mar 3rd, 2011
1 [15:55] <dholbach> HELLO MY FRIENDS! WELCOME TO DAY 4 of UBUNTU DEVELOPER WEEK! 2 [15:56] <dholbach> if you need any information at all (which sessions, etc.) head to: https://wiki.ubuntu.com/UbuntuDeveloperWeek 3 [15:56] <dholbach> also... if you haven't joined #ubuntu-classroom-chat yet, you might want to do that now 4 [15:56] <dholbach> because that's where we chat and ask questions 5 [15:56] <dholbach> if you have questions, please ask - we want our sessions to be as interactive as possible 6 [15:57] <dholbach> if you do ask, please make sure you prefix your question with QUESTION: 7 [15:57] <dholbach> ie: QUESTION: Which language should become default language of Ubuntu? 8 [15:58] <dholbach> The first session of the day is lead by an awesome guy, a friend and colleague of mine, who probably has an opinionated answer to the last question 9 [15:58] <dholbach> it's David Planella, Mr. dpm 10 [15:58] <dholbach> who is going to talk about hooking up your application with Launchpad Translations 11 [15:59] <dholbach> dpm, you still have a few minutes until you get started :) 12 [15:59] <dholbach> have a great day 4 every one - enjoy the sessions! 13 [16:00] <dpm> Thanks dholbach, I've got the right answer to that question, but we'll leave it for another full session :) 14 [16:00] <dholbach> of course you do :) 15 [16:00] <dholbach> enjoy! 16 [16:00] <dpm> ;) 17 === ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - https://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Questions in #ubuntu-classroom-chat || Event: Ubuntu Developer Week - Current Session: Integrating your package with Launchpad Translations - Instructors: dpm 18 [16:01] <dpm> Let's wait a couple of minutes for everyone to join in, and then we can get started 19 [16:01] <ClassBot> Logs for this session will be available at http://irclogs.ubuntu.com/2011/03/03/%23ubuntu-classroom.html following the conclusion of the session. 20 [16:03] <dpm> Ok, let's get started... 21 [16:03] <dpm> Hi all 22 [16:04] <dpm> Welcome to this Ubuntu Developer Week talk on integrating your package with Launchpad Translations 23 [16:05] <dpm> I'm David Planella, from the Community team at Canonical, and my job as the Ubuntu Translations Coordinator is to make sure, with the help of our awesome translations community, that Ubuntu rocks equally hard in every language. 24 [16:05] <dpm> Today I'd like to get a bit more technical and explain how you can make sure your package is well integrated with the Launchpad Translations web app, 25 [16:06] <dpm> so that Ubuntu translators can happily do their work and provide a well localized OS to our users. 26 [16:06] <dpm> Just to give you a brief summary, here's how it will go: 27 [16:06] <dpm> We'll first start with a couple of background subjects, then we'll go more into the details related to packaging and finally we'll wrap it up with a Q+A session 28 [16:07] <dpm> If you have questions during the session though, feel free to interrupt and ask me on #ubuntu-classroom-chat 29 [16:07] <dpm> So, without further ado... 30 [16:07] <dpm> Let's roll 31 [16:07] <dpm> Integrating Your Package with Launchpad Translations 32 [16:07] <dpm> ==================================================== 33 [16:07] <dpm> So, as mentioned in the intro, the idea of this talk is to give you an overview of what is needed in your package to play well with Launchpad and for their translations to be exposed to translators there. 34 [16:08] <dpm> Note that this only essentially applies to packages in the main and restricted repositories (and additionally for the -security, -proposed and -updates pockets). 35 [16:09] <dpm> Only their translations will be imported into Launchpad and delivered in language packs (more on this in a few minutes). 36 [16:09] <dpm> Packages in universe, multiverse, etc. will not be translatable in Launchpad, and translations will be shipped with the packages and have no direct interaction with Launchpad or the language pack infrastructure. 37 [16:09] <dpm> i.e. they will be shipped as they come from upstream 38 [16:10] <dpm> First of all, I'll start with a bit of background for those of you not yet too all familiar with translations 39 [16:10] <dpm> Launchpad Translations 40 [16:10] <dpm> ---------------------- 41 [16:10] <dpm> As you might know, in Ubuntu we use our very own translations tool: Launchpad Translations 42 [16:11] <dpm> Launchpad Translations allows distributed translation of our Operating System, by a large number of volunteer contributors, who work hard to ensure Ubuntu is well localized for everyone to use it in their own language. 43 [16:11] <dpm> You can see the Ubuntu translations here: https://translations.launchpad.net/ubuntu 44 [16:11] <dpm> (you can choose a distro series there, e.g. Natty to see the stats) 45 [16:12] <dpm> There you'll see a list of translatable applications and documentation, ordered by priority 46 [16:12] <dpm> Ubuntu is currently translated in more than 200 languages, with different levels of coverage, and can easily support more. 47 [16:12] <dpm> You can see the languages supported of in the last stable version of Ubuntu here: 48 [16:12] <dpm> http://people.ubuntu.com/~dpm/ubuntu-10.10-translation-stats.html 49 [16:12] <dpm> Many of those translations are done by upstream translation communities, and they also get imported into Launchpad during package uploads 50 [16:13] <dpm> The Ubuntu Translations Community 51 [16:13] <dpm> --------------------------------- 52 [16:13] <dpm> I won't dwell too much on this subject, as I think as a packager you might be more focused on the technical side of things. 53 [16:13] <dpm> Nevertheless, I'd like to add a few words about the Ubuntu Translations community, since I think, be it for the subject of this talk, or be it because we are all part of the bigger Ubuntu family, it is important for those working directly or indirectly with translations to know more about it. 54 [16:14] <dpm> Ubuntu Translators are a vast number of volunteers who organise themselves in translation teams, appointed to be responsible for the translation of a given language. 55 [16:14] <dpm> And they just rock. 56 [16:14] <dpm> You can see the full list of Ubuntu translation teams here: 57 [16:15] <dpm> https://translations.launchpad.net/+groups/ubuntu-translators 58 [16:15] <dpm> With your translation uploads you'll be enabling them to deliver Ubuntu in hundreds of languages, to many, many people 59 [16:15] <dpm> So time to feel proud now :) 60 [16:15] <dpm> Language Packs 61 [16:15] <dpm> -------------- 62 [16:16] <dpm> btw, I guess there were no questions so far, if there is anything that was not clear, feel free to ask 63 [16:17] <dpm> In Ubuntu we ship all translations in dedicated .deb packages called language packs 64 [16:17] <dpm> Packages in main and restricted don't contain translations in the form of .mo files themselves 65 [16:18] <dpm> (if you are not familiar with them, .mo files are a type of binary files where translations are loaded from at runtime. The source for translations are textual .po files that get compiled into the final .mo files) 66 [16:18] <dpm> They are stripped during the build on the Launchpad buildds and put into the language-pack-* packages instead. 67 [16:19] <dpm> There is a set of language packs per language 68 [16:20] <dpm> They are divided roughly between generic translations and those which are used in a GNOME-based desktop and those used in a KDE-based desktop 69 [16:20] <dpm> We essentially make use of language packs to deliver translations independently from applications and thus we're able to ship regular translation updates throughout a distro series lifecycle. 70 [16:21] <dpm> Translations Import Workflow 71 [16:21] <dpm> ---------------------------- 72 [16:22] <dpm> On a 1000 feet view, what happens when you do a package upload is that their translations get stripped by a tool called pkgbinarymangler, and they are put in a translations tarball containing a translations template (more on this later on) and the translations themselves. 73 [16:22] <dpm> This tarball is then fed to Soyuz, which ends up handing it to the translations imports queue. There, they will be eventually processed, approved and imported into Launchpad, at which point they will be exposed in the translations web interface ready for translators to do their job. 74 [16:24] <dpm> If you are interested in seeing what the imports queue looks like, you can see the translation uploads currently pending review here: 75 [16:24] <dpm> https://translations.launchpad.net/ubuntu/natty/+imports?field.filter_extension=pot&field.filter_status=NEEDS_REVIEW&start=75&batch=75 76 [16:24] <dpm> That's the global imports queue, but you can see it per package as well 77 [16:25] <dpm> https://translations.launchpad.net/ubuntu/natty/+source/gtkhtml3.14/+imports 78 [16:25] <dpm> There's an example ^ 79 [16:26] <dpm> So now we come to the nitty gritty details... :) 80 [16:27] <dpm> let's try to answer some of the questions first... 81 [16:27] <ClassBot> monish001 asked: Are we taking here about the time of package installation - "stripped during the build on the Launchpad buildds and put into the language-pack-* packages instead." 82 [16:28] <dpm> No, the translations are stripped during the package build. By the time the package is installed, translations are no longer in the package 83 [16:28] <dpm> They will be in the language packs instead 84 [16:28] <ClassBot> chadadavis asked: when translations from different packages are merged into a language pack, how do you check that expressions like "File not found" are translated consistently between applications? 85 [16:29] <dpm> That's something that as a packager you cannot ensure, so you'll be relying on translators to work consistently 86 [16:29] <dpm> Launchpad also helps on that, giving global suggestions for translations which have the same original message in other projects 87 [16:30] <dpm> What I'm trying to say is that this is something translators are used to deal with 88 [16:30] <dpm> and translation consistency is part of their work 89 [16:30] <dpm> ok, let's move on then 90 [16:30] <dpm> Package Modifications for a better Ubuntu integration 91 [16:30] <dpm> ----------------------------------------------------- 92 [16:31] <dpm> In order for translations to be imported to Launchpad and in order to direct translators to the translations page to start contributing straight away, 93 [16:31] <dpm> we make two main changes to the application at the packaging level: 94 [16:31] <dpm> * Creation of a POT file on build - We require the .deb package to produce a .pot translation template during the build, which will be imported into Launchpad and be used to expose translations for translators to do their work. 95 [16:31] <dpm> * Addition of the Launchpad integration library - We add some functionality to display some additional entries to the Help menu, to direct contributors to Launchpad to report bugs, submit translations and get help. 96 [16:32] <dpm> For those not familiar with the concept of a POT template: 97 [16:32] <dpm> It's a textual file with the .pot extension 98 [16:33] <dpm> and it's what Launchpad use as the source for exposing translations 99 [16:33] <dpm> all translations in all languages will be based on that template, which contains the translatable messages in English 100 [16:34] <dpm> It's generally built by gettext-based tools 101 [16:34] <dpm> which extract translatable messages from the code in an application 102 [16:34] <dpm> and put them in the textual .pot file 103 [16:34] <dpm> Generating POT templates 104 [16:34] <dpm> ~~~~~~~~~~~~~~~~~~~~~~~~ 105 [16:34] <dpm> For pkgstriptranslations (in the pkgbinarymangler package) to do the job right and translations to be imported into Launchpad, 106 [16:35] <dpm> you should make sure that your package in main or restricted generates a POT translation template during the build. 107 [16:35] <dpm> It does not necessarily need to be shipped in the source or in the binary package. 108 [16:35] <dpm> Generating it during the build is good enough. 109 [16:35] <dpm> -> Note that if your package does not generate a POT template on build, its translations will remain as Blocked in the Launchpad Translations import queue and will not be imported 110 [16:35] <dpm> So it's important to get this right 111 [16:36] <dpm> The most common approaches are running either of the following in the debian/rules file: 112 [16:36] <dpm> * For packages using CDBS and automake: 113 [16:36] <dpm> * You just need to include /usr/share/cdbs/1/rules/langpack.mk in debian/rules 114 [16:36] <dpm> * If the package is a GNOME one, and you are using the gnome.mk CDBS class already, you should be good to go, since it already includes langpack.mk 115 [16:36] <dpm> * If for some reason the POT template cannot be generated during the build, see the next points below. 116 [16:37] <dpm> * Other packages, using intltool usually require: 117 [16:37] <dpm> * A call to intltool-update -p in debian/rules, or 118 [16:37] <dpm> * a call to an already existing Makefile target to build the POT (this does exist quite often in fact). 119 [16:37] <dpm> * For packages which don't use intltool: 120 [16:38] <dpm> * Need to get fixed individually: 121 [16:38] <dpm> * Usually by adding a call to xgettext and po/POTFILES.in, or 122 [16:38] <dpm> * Finding an already existing Makefile target. e.g. Use $(MAKE) -C po update-po instead of (cd po; make update-po; cd ..). Example in the debian/rules file from upower: 123 [16:38] <dpm> common-post-build-arch:: 124 [16:38] <dpm> make -C po upower.pot 125 [16:38] <dpm> * Packages which use python-distutils-extra: 126 [16:39] <dpm> * Template creation should happen automagically :) 127 [16:39] <dpm> oh, btw: 128 [16:40] <dpm> Gettext is the underlying and most widely used technology to enable translations of Open Source projects. 129 [16:40] <dpm> Intltool is a higher level tool that adds functionality to gettext by allowing the extraction of translatable strings from a variety of file formats. 130 [16:40] <dpm> Questions so far? 131 [16:41] <dpm> Is it clear that Ubuntu packages need to generate a .pot file during the build? 132 [16:41] <dpm> ok, next then 133 [16:41] <dpm> The Launchpad Integration Library 134 [16:41] <dpm> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 135 [16:42] <dpm> Ubuntu applications use the Launchpad integration library to provide shortcuts to Launchpad to obtain help, report bugs and submit translations. 136 [16:42] <dpm> You can see it in action in every application's help menu, and it lives here: 137 [16:42] <dpm> https://launchpad.net/launchpad-integration 138 [16:42] <dpm> Note that this only works for Ubuntu packages available in the repositories. The Launchpad integration library does not work with PPAs or other projects hosted in Launchpad. 139 [16:42] <dpm> It has bindings for several languages. An example in Python: 140 [16:43] <dpm> import LaunchpadIntegration 141 [16:43] <dpm> LaunchpadIntegration.set_sourcepackagename('my_app') 142 [16:43] <dpm> LaunchpadIntegration.add_items(self.builder.get_object('menu_help'), 0, False, True) 143 [16:43] <dpm> Unless the packaged application itself makes use of it already, you should add it as a patch. 144 [16:43] <dpm> If you want to see a couple of examples, these bugs will help you learning how you can add support for the Launchpad Integration Library to your package: 145 [16:44] <dpm> https://bugs.launchpad.net/bugs/436742 146 [16:44] <dpm> https://bugs.launchpad.net/bugs/508395 147 [16:44] <dpm> Verifying Packages 148 [16:44] <dpm> ------------------ 149 [16:44] <dpm> Finally, here is a small recipe and some guidelines to help you test and optimize your packages, so that translation-related files get automatically imported seamlessly into Launchpad. 150 [16:44] <dpm> Generally, you will only need to do this once when setting up your package the first time, altough it can also be useful to debug import problems, for example 151 [16:49] <dpm> Testing the package locally 152 [16:49] <dpm> ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 153 [16:49] <dpm> To test if your package conforms to the requirements of the import script in the Launchpad imports queue, you can do the following: 154 [16:50] <dpm> oops short disconnection :) 155 [16:50] <dpm> anyway, let's continue... 156 [16:50] <dpm> * Template name and domain: the filename of the template (.pot file) should be the same as what the expected translation domain is. 157 [16:51] <dpm> * Translation filenames: the actual translations (.po files) must have a filename of the format $LANGUAGECODE.po or $LOCALECODE.po (e.g. de.po, pt_BR.po, zh_TW.po) 158 [16:51] <ClassBot> There are 10 minutes remaining in the current session. 159 [16:51] <dpm> * Template and translations location: all translation-related files (the .pot template and its corresponding .po templates) must end up in the same (sub-)directory if possible. 160 [16:51] <dpm> * Obsolete translations: if there are .po files present in the package but no associated .pot template, please remove them, since they cannot be used without a .pot template. 161 [16:51] <dpm> * Valid POT template: please check if the .pot file has any meaningful content. Empty .pot files should best be removed and the package build rules be fixed. 162 [16:52] <dpm> * Templates generated by patches: if your package contains patches and those patches result into extra templates, like patches.pot, please merge those changes into the main template 163 [16:52] <dpm> Anyway, that was it for the session content, 164 [16:52] <dpm> I hope you found it useful 165 [16:53] <dpm> If you've got any questions related to the session or to translations in general, now feel free to ask! :-) 166 [16:53] <dpm> Q+A 167 [16:53] <dpm> --- 168 [16:53] <ClassBot> chadadavis asked: does the Launchpad integration provide any services for PPA packages? Since it's not officially supported/working on those? 169 [16:54] <dpm> As far as I know, it works only if there is a package available in the Ubuntu repositories, but I haven't tried it with PPAs 170 [16:55] <dpm> Any more questions? 171 [16:56] <ClassBot> There are 5 minutes remaining in the current session. 172 === mdeslaur_ is now known as mdeslaur 173 [16:58] <dpm> ok then, if there are no more questions we'll wrap up early 174 [16:58] <dpm> Thank you very much for your attention, I hope you enjoyed it and I hope to see you soon! 175 [16:59] <dpm> I'll now leave you in the able hands of Kaleo, who'll tell you all about Getting Started with Unity 2D!! 176 [16:59] <dpm> Enjoy!