launchpad-dev team mailing list archive

[Matthew Revell <matthew.revell@xxxxxxxxxxxxx>]

2009/8/11 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!

I agree we should be careful not to fragment the help pages but I
think each of these can benefit from separate articles, not least so
that we can more easily link to specific articles but also to avoid
overwhelming people -- or, as you say, to make it so people can see
the bottoms of the pages :)

>> https://help.launchpad.net/Translations/YourProject/Draft
>
> I like the Important/Quick tip/Note boxes!

Great, I really wanted to something to break up the mass of text.

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

Thanks, fixed.

>> 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've changed it to:

You can choose from two methods of importing translation templates:

    * recommended: automatic and ongoing imports of your templates,
and optionally also translation files, from a Bazaar branch you
specify
    * or manually upload .pot files using the web interface.

I think that works better.

> 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.

I take point 1 but I'm not sure I really see the confusion here. I
think it's important to provide one most-likely route. I've added a
sub-section on importing from external repos though.

> 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.
>

Thanks, fixed.

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

Also fixed.

> Under "Naming template," is it really true that "a template file does not
> carry any metadata"?  It contains a header, after all.

One of the Translations team wrote that part and I simply adapted it :)

>  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."

Thanks, I've used that.

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

Ah, of course.

> 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."

Much better.

> 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?

Fixed.

>> 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!

Many thanks.

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

I'll fix those on my final sweep before publication.

-- 
Matthew Revell - Launchpad.net - free software collaboration and project hosting