launchpad-dev team mailing list archive

[Jeroen Vermeulen <jtv@xxxxxxxxxxxxx>]

Matthew Revell wrote:

> I've rewritten the help guide for projects wanting to use LP to
> translate their software and would love your feedback.

These are pretty small tasks... hope the pages don't become too 
fragmentary.  But definitely good to give the user pages they can see 
the bottoms of!


> https://help.launchpad.net/Translations/YourProject/Draft

I like the Important/Quick tip/Note boxes!

Missing "about" in this link, I think: "Read more translation licensing."

Oh well, you know me, never too busy to pick a nit if you ask me to.  :-)


> https://help.launchpad.net/Translations/YourProject/ImportingTemplates/Draft

This paragraph, to my mind, needs qualifying:

"Launchpad can automatically import your translation templates from a 
Bazaar branch. Each time you commit a change in your templates to your 
Bazaar branch, and then push the branch to Launchpad, Launchpad will 
update the strings available for translation in your project."

This seems to suggest that these imports will happen without any further 
configuration.  The "Enabling automatic template imports" header later 
dispels that, but the first impression has a way of sticking around.

I find the "Push the branch to Launchpad" section a bit confusing, 
simply because this is all so flexible.  I don't have much in the way of 
suggestions, except (1) the exact push instruction is shown on the main 
page for each branch, and (2) it may be worth saying that there are many 
choices, so that the reader isn't left wondering why the text isn't more 
specific.

Under "Adding and updating templates," first paragraph, committing a 
file isn't really all you need to do: you need to push it, too!  Might 
trip up users not used to DCVS.

Also, that section mentions "product series."  I think that's code-speak 
and "release series" would fit better.

Under "Naming template," is it really true that "a template file does 
not carry any metadata"?  It contains a header, after all.  I'd say 
something like:

"There can be many templates in a project.  When a file comes in, 
Launchpad needs to figure out which known template it belongs to--or 
whether it's a completely new template.  It does this based on the 
template's file path."

Maybe it's not worth introducing the word metadata here, and instead 
going on:

"Every known template in your project has two identifiers: its
"name" is used to show and refer to the template in Launchpad's user 
interface.  The other is its "translation domain," which is used in 
filenames.  Launchpad will pick both based on your template file's path."

Under "Automatic approval," be sure to mention that this topic literally 
makes the difference between minutes and days of waiting time.

Rather than "If the template is to be added," I would say "If this 
template is a new one."  I also think there must be a better way of 
wording "no template entry must exist in Launchpad Translations that 
does not have a matching template file in the branch."  Something like, 
"the branch should still contain a .pot file for each of the already 
known templates in your release series."

This part is a bit academic and seems to see things more from our 
perspective than from the user's.  Instead of "The latter condition is 
there to avoid creating new template entries when in reality the 
existing template entry was to be renamed," I'd say something more 
informal and user-oriented like "That last rule is there so Launchpad 
can see that the template is really new, and not an existing template 
being renamed."

Under "Manual translation template imports" I'd say "tar archive" rather 
than just "archive."

Also, just above the "Next steps" heading, why should I visit my 
project's translations overview page and click the link for the trunk 
series?


> https://help.launchpad.net/Translations/YourProject/ImportingTranslations/Draft
> https://help.launchpad.net/Translations/YourProject/Policies/Draft
> https://help.launchpad.net/Translations/YourProject/ChoosingAGroup/Draft
> https://help.launchpad.net/Translations/YourProject/Exports/Draft
> https://help.launchpad.net/Translations/YourProject/Exports/Draft

I'll get to these soon.  Thanks for doing this!


Jeroen

PS: I see some inconsistency in emdashes... type 
<compose><dash><dash><dash> to get the real thing.