Merge lp:~songofacandy/bzr/i18n-command into lp:bzr

[methane]

Translate command help

[Vincent Ladeuil (vila)]

8 +

Spurious ?

20 + i18n.uninstall()
21 +

Hmm, that's weird, who did install what ? Why do we need to start
uninstalling ?

Said otherwise, this reveals some weird initialization and I
think we want a better way to achieve it.

To avoid a controversial discussion about general deployment I
think you should focus on initializing the i18n/i10n only for the
help command. We can revisit that later once we are happy with
the results.

46 + # NOTE: If cmd_gettext translates ':Usage:\n', the section will
47 + # be shown after "Description" section.
48 + doc = cmd_gettext(doc)

/me blinks

I'm sure this will be eaiser to understand if you added a
corresponding test.

58 - result += ':Purpose: %s\n' % purpose
59 + result += ':%s: %s\n' % (gettext('Purpose'), purpose)

Hmm, this pattern will probably occurs quite frequently and I'm
pretty sure the translators will sometimes need to tweak the
format Is there some existing facility we can reuse so this can
be spelt something like:

  result += gettext(':Purpose: %s\n' % (gettext(purpose),)

or even better:

  result += gettext_xxx(':Purpose: %(purpose)s\n', dict(purpose=purpose))

?

74 + options = option.get_optparser(self.options(), True)
75 + options = options.format_option_help()

How about:

 parser = option.get_optparser(self.options(), True)
 options = parser.format_option_help()

88 + if options.startswith('Options:') or options.startswith('options:'):
89 + # Python 2.4 version of optparse uses 'options'.
90 + result += ':%s:%s' % (gettext('Options'), options[len('options:'):])

Forget about python-2.4, we don't support it anymore.

135 - sys.stdout.write(self.get_help_text())
136 + self._setup_outf()
137 + self.outf.write(self.get_help_text())
138 return 0
139 if 'usage' in opts: # e.g. bzr add --usage
140 sys.stdout.write(self.get_help_text(verbose=False))

/me blinks

Nice to address this bug, but why on earth is it needed ? This
should really be addressed far earlier no ? Can you find where or
do you need help here ?

Also, it looks like the exact same bug affect 'usage'. I realize
this may be out of scope for this proposal, so may be we want a
different proposal that, just let me know if you want to do it or
leave it to me.

145 + @staticmethod
146 + def get_gettext():

I don't understand why you need a static method there ? I realize
*you* don't need 'self' but may be some plugins will, no ?

149 + NOTE: Commands provided by plugins should override this to use own
150 + i18n system.

typo/style nits: We don't use 'NOTE:' all caps, may be just 'Note:' or may be just nothing ;) s/to use own/to use their own/

165 + opt_no_i18n = opt_no_aliases = False

Excuse my ignorance, but shouldn't that be opt_no_i10n here ?

182 + if not opt_no_i18n:
183 + # selftest uninstalls i18n later.
184 + i18n_install()

Ha ! Here is the install !

So, yeah, it will be clearer to start with if install/uninstall
is done by the help command only and the appropriate tests,
keeping it under control will help us understand how/when/where
it's needed.

We had trouble in the past about such global options, I'd rather
avoid the fallbacks right from the start.

This is by no means a lack of trust, I'm just being caut...

review: Needs Information

[Vincent Ladeuil (vila)]

Also ! This proposal is a significant step in the i10n process as it will lead to the first visible results for our users so it definitely deserves news entries (and credits !).

Don't worry about writing imperfect English, we'll find native speakers to catch *my* spelling mistakes :)

[methane (songofacandy)]

> 8 +
>
> Spurious ?

I've removed it.

>
> 20 + i18n.uninstall()
> 21 +
>
> Hmm, that's weird, who did install what ? Why do we need to start
> uninstalling ?

I think of many other commands like log or status use i18n in the future.
I18n only breaks selftest.

>
> Said otherwise, this reveals some weird initialization and I
> think we want a better way to achieve it.
>
> To avoid a controversial discussion about general deployment I
> think you should focus on initializing the i18n/i10n only for the
> help command. We can revisit that later once we are happy with
> the results.

I am not against on enabling i18n only for help command until other
commands needs i18n.

But, how? When selftest calls help, enabling i18n breaks many tests.
I don't think replacing `i18n.uninstall()` with global variable like
`opt_no_i18n=True` is beautiful answer.

One idea come to my mind is adding `use_i18n = False` class attribute
to the Command class. The cmd_help overrides it with `use_i18n = True`.
Then, selftest overrides `use_i18n = False` again.

Do you think OK with this idea?

[Vincent Ladeuil (vila)]

> I think of many other commands like log or status use i18n in the future.

I expect so !

> I18n only breaks selftest.

Let's focus on that then.

> I am not against on enabling i18n only for help command until other
> commands needs i18n.

Cool.

>
> But, how? When selftest calls help, enabling i18n breaks many tests.

I think we don't want to blindly activate i18n during tests. Quite the contrary, we probably want to *never* activate it by default (which should translate to either totally disabling any i18n code or may be just using a NullTranslation ?)

So, this kind of isolation is generally done in bzrlib.tests.TestCase, if you push a revision with some tests failing, I should be able to fix that.

[methane (songofacandy)]

> 46 + # NOTE: If cmd_gettext translates ':Usage:\n', the section will
> 47 + # be shown after "Description" section.
> 48 + doc = cmd_gettext(doc)
>
> /me blinks
>
> I'm sure this will be eaiser to understand if you added a
> corresponding test.

Is the test for garbage input and garbage output really needed?

I've modified export-pot commands to don't exports paragraph starting
with ":Usage:". I think this is not beautiful but enough.

>
> 58 - result += ':Purpose: %s\n' % purpose
> 59 + result += ':%s: %s\n' % (gettext('Purpose'), purpose)
>
> Hmm, this pattern will probably occurs quite frequently and I'm
> pretty sure the translators will sometimes need to tweak the
> format Is there some existing facility we can reuse so this can
> be spelt something like:
>
> result += gettext(':Purpose: %s\n' % (gettext(purpose),)
>
> or even better:
>
> result += gettext_xxx(':Purpose: %(purpose)s\n', dict(purpose=purpose))
>
> ?

OK, gettext(':Purpose: %s\n') % (gettext(purpose),) may be good.

>
> 74 + options = option.get_optparser(self.options(), True)
> 75 + options = options.format_option_help()
>
> How about:
>
> parser = option.get_optparser(self.options(), True)
> options = parser.format_option_help()
>
> 88 + if options.startswith('Options:') or options.startswith('options:'):
> 89 + # Python 2.4 version of optparse uses 'options'.
> 90 + result += ':%s:%s' % (gettext('Options'), options[len('options:'):])
>
> Forget about python-2.4, we don't support it anymore.
>

I'll fix.

> 135 - sys.stdout.write(self.get_help_text())
> 136 + self._setup_outf()
> 137 + self.outf.write(self.get_help_text())
> 138 return 0
> 139 if 'usage' in opts: # e.g. bzr add --usage
> 140 sys.stdout.write(self.get_help_text(verbose=False))
>
> /me blinks
>
> Nice to address this bug, but why on earth is it needed ? This
> should really be addressed far earlier no ? Can you find where or
> do you need help here ?

It was not problem before because get_help_text() returns bytestring
containing only ascii characters.
Since i18n is enabled, get_help_text() returns unicode though `outf`
is needed.

>
> Also, it looks like the exact same bug affect 'usage'. I realize
> this may be out of scope for this proposal, so may be we want a
> different proposal that, just let me know if you want to do it or
> leave it to me.

Ah, I've forgot to address --usage. I'll fix it.

>
>
> 145 + @staticmethod
> 146 + def get_gettext():
>
> I don't understand why you need a static method there ? I realize
> *you* don't need 'self' but may be some plugins will, no ?
>
> 149 + NOTE: Commands provided by plugins should override this to use own
> 150 + i18n system.
>
> typo/style nits: We don't use 'NOTE:' all caps, may be just 'Note:' or may be
> just nothing ;) s/to use own/to use their own/
>

I'll fix these.

> 165 + opt_no_i18n = opt_no_aliases = False
>
> Excuse my ignorance, but shouldn't that be opt_no_i10n here ?

Do you mean "l10n"?
I agree on "opt_no_l10n" or "opt_no_L10N" is better than "i10n".

>
> 196 + if p.splitlines()[0] == ':Usage:':
> 197 +...

[Vincent Ladeuil (vila)]

>>>>> INADA Naoki <email address hidden> writes:

    >> 46 + # NOTE: If cmd_gettext translates ':Usage:\n', the section will
    >> 47 + # be shown after "Description" section.
    >> 48 + doc = cmd_gettext(doc)
    >>
    >> /me blinks
    >>
    >> I'm sure this will be eaiser to understand if you added a
    >> corresponding test.

    > Is the test for garbage input and garbage output really needed?

later you have:

221 + def filter(p):
222 + # ':Usage:' has special meaning in help topics.
223 + # This is usage example of command and should not be translated.
224 + if p.splitlines()[0] == ':Usage:':
225 + return True

Reading that, I think I understand. The later is needed to prepare the
file for translators while the former is making sure we don't try to
translate when we display the command help. Is that right ?

    > I've modified export-pot commands to don't exports paragraph
    > starting with ":Usage:". I think this is not beautiful but enough.

Indeed, now it makes sense, sorry for being a bit obtuse here :)

So I think what I wanted is:

    >> 46 + # NOTE: If cmd_gettext translates ':Usage:\n', the section will
    >> 47 + # be shown after "Description" section.

# be shown after "Description" section and we don't want to translate the usage string.

But we still want to translate 'Usage' itself right ? Like we want to
translate 'Description', 'Tips', 'See Also' and so on. Do we reuse these
specifics strings from somewhere or are they part of the strings our
translators will process ?

(Also see below for other related points)

<snip/>

    > OK, gettext(':Purpose: %s\n') % (gettext(purpose),) may be good.

Right, that looks like an easier idiom.

    >> 135 - sys.stdout.write(self.get_help_text())
    >> 136 + self._setup_outf()
    >> 137 + self.outf.write(self.get_help_text())
    >> 138 return 0
    >> 139 if 'usage' in opts: # e.g. bzr add --usage
    >> 140 sys.stdout.write(self.get_help_text(verbose=False))
    >>
    >> /me blinks
    >>
    >> Nice to address this bug, but why on earth is it needed ? This
    >> should really be addressed far earlier no ? Can you find where or
    >> do you need help here ?

    > It was not problem before because get_help_text() returns bytestring
    > containing only ascii characters.
    > Since i18n is enabled, get_help_text() returns unicode though `outf`
    > is needed.

Sorry, badly phrased. I understand why we need to use outf, I don't
understand why we need to call set_outf (or rather why it has not been
already called).

    >>
    >> Also, it looks like the exact same bug affect 'usage'. I realize
    >> this may be out of scope for this proposal, so may be we want a
    >> different proposal that, just let me know if you want to do it or
    >> leave it to me.

    > Ah, I've forgot to address --usage. I'll fix it.

Right, so same fix twice, hence my worries about why we need to fix that
as it seems to reveal a deeper issue...

    >>
    >>
    >> 145 + @staticmethod
    >> 146 + def get_gettext():
    >>
    >> I don't understand why you need a static method there ? I realize
    >> *you* don't need 's...

[Martin Pool (mbp)]

I'd like a second opinion but this looks good to me.

It may make future reviews faster if you can summarize the change in the mp
description.
On Jun 1, 2011 6:42 PM, "INADA Naoki" <email address hidden> wrote:
> INADA Naoki has proposed merging lp:~songofacandy/bzr/i18n-command into
lp:bzr.
>
> Requested reviews:
> Vincent Ladeuil (vila)
>
> For more details, see:
> https://code.launchpad.net/~songofacandy/bzr/i18n-command/+merge/62752
>
> Translate command help
> --
> https://code.launchpad.net/~songofacandy/bzr/i18n-command/+merge/62752
> Your team bzr-core is subscribed to branch lp:bzr.

[methane (songofacandy)]

> >>>>> INADA Naoki <email address hidden> writes:
>
> >> 46 + # NOTE: If cmd_gettext translates ':Usage:\n', the section
> will
> >> 47 + # be shown after "Description" section.
> >> 48 + doc = cmd_gettext(doc)
> >>
> >> /me blinks
> >>
> >> I'm sure this will be eaiser to understand if you added a
> >> corresponding test.
>
> > Is the test for garbage input and garbage output really needed?
>
> later you have:
>
> 221 + def filter(p):
> 222 + # ':Usage:' has special meaning in help topics.
> 223 + # This is usage example of command and should not be translated.
> 224 + if p.splitlines()[0] == ':Usage:':
> 225 + return True
>
> Reading that, I think I understand. The later is needed to prepare the
> file for translators while the former is making sure we don't try to
> translate when we display the command help. Is that right ?

Yes, I want to avoid translating ':Usage:' because it is used as a keyword
in Command.get_help_text().

>
> > I've modified export-pot commands to don't exports paragraph
> > starting with ":Usage:". I think this is not beautiful but enough.
>
> Indeed, now it makes sense, sorry for being a bit obtuse here :)
>
> So I think what I wanted is:
>
> >> 46 + # NOTE: If cmd_gettext translates ':Usage:\n', the section
> will
> >> 47 + # be shown after "Description" section.
>
> # be shown after "Description" section and we don't want to translate the
> usage string.

OK, I'll fix the comment.

>
> But we still want to translate 'Usage' itself right ? Like we want to
> translate 'Description', 'Tips', 'See Also' and so on. Do we reuse these
> specifics strings from somewhere or are they part of the strings our
> translators will process ?
>
> (Also see below for other related points)

Yes, get_help_text() removes ":Usage:" in the docstring and write separately.

> result += gettext(':Usage:\n%s') % (usage,) + '\n'

> >> 135 - sys.stdout.write(self.get_help_text())
> >> 136 + self._setup_outf()
> >> 137 + self.outf.write(self.get_help_text())
> >> 138 return 0
> >> 139 if 'usage' in opts: # e.g. bzr add --usage
> >> 140 sys.stdout.write(self.get_help_text(verbose=False))
> >>
> >> /me blinks
> >>
> >> Nice to address this bug, but why on earth is it needed ? This
> >> should really be addressed far earlier no ? Can you find where or
> >> do you need help here ?
>
> > It was not problem before because get_help_text() returns bytestring
> > containing only ascii characters.
> > Since i18n is enabled, get_help_text() returns unicode though `outf`
> > is needed.
>
> Sorry, badly phrased. I understand why we need to use outf, I don't
> understand why we need to call set_outf (or rather why it has not been
> already called).
>
> >>
> >> Also, it looks like the exact same bug affect 'usage'. I realize
> >> this may be out of scope for this proposal, so may be we want a
> >> different proposal that, just let me know if you want to do it or
> >> leave it to me.
>
> > Ah, I've forgot to address --usag...

[methane (songofacandy)]

Then, I'll remove translating option help in this mp.

I'll add a new class that inherits OptionParser and overrides
format_option_help() in future mp.

[Vincent Ladeuil (vila)]

> Then, I'll remove translating option help in this mp.
>
> I'll add a new class that inherits OptionParser and overrides
> format_option_help() in future mp.

That sounds like the best way to move forward.

Mark this proposal NeedsReview when you're ready.

[methane (songofacandy)]

I think I've done what I said "I'll do it."
Anything else?

[Vincent Ladeuil (vila)]

>>>>> INADA Naoki writes:

    > I think I've done what I said "I'll do it."
    > Anything else?

Sorry for the delay I had some lag in my mail.

I'll look into it asap.

[Vincent Ladeuil (vila)]

So, the bad news first: 6 test failures:

bzrlib.tests.test_help.TestCommandHelpI18n.test_command_help_includes_see_also
bzrlib.tests.test_help.TestCommandHelpI18n.test_command_only_additional_see_also
bzrlib.tests.test_help.TestCommandHelpI18n.test_command_with_additional_see_also
bzrlib.tests.test_help.TestCommandHelpI18n.test_get_help_text
bzrlib.tests.test_help.TestCommandHelpI18n.test_help_custom_section_ordering
bzrlib.tests.test_help.TestCommandHelpI18n.test_help_text_custom_usage

I made some modifications to make these failures easier to diagnose (in lp:~vila/bzr/i18n-command) but you didn't merge them.

The good news now: I've merged these modifications again and what
happens is that your last commit broke them by installing the
"right" _translations (NullTranslation) when translating the
command help which defeats the installation done by the tests.

Also, these modifications included removing your modification
pattern:

60 - result += ':Purpose: %s\n' % purpose
61 + result += gettext(':Purpose: %s') % (purpose,) + '\n'

Specifically, I'm talking about removing the '\n' from the string
to be translated. If you have a strong reason to do so, let's put
it back and let's to do it everywhere it matters.

For i18n._translations, what we want is a lazy installation so
that it's done only once and that tests can force a specific
translation. This way, we can (as we do now) activate a
translation only when we need it: to generate the command help.

I went ahead and:

- initialize i18n._translation to None instead of NullTranslations,

- spell '_translations' with a final 's' (for consistency with
  gettext itself and ZzzTranslationsForDoc)

I'll land with these modifications and a news entry (please
review it and let me know what you think).

review: Approve

=== modified file 'bzrlib/builtins.py'
--- bzrlib/builtins.py	2011-06-16 16:45:18 +0000
+++ bzrlib/builtins.py	2011-06-23 16:06:27 +0000
@@ -3728,6 +3728,7 @@
             randomize=None, exclude=None, strict=False,
             load_list=None, debugflag=None, starting_with=None, subunit=False,
             parallel=None, lsprof_tests=False):
+        from bzrlib import i18n
         from bzrlib import tests
 
         if testspecs_list is not None:

=== modified file 'bzrlib/commands.py'
--- bzrlib/commands.py	2011-05-19 09:32:38 +0000
+++ bzrlib/commands.py	2011-06-23 16:06:27 +0000
@@ -44,6 +44,11 @@
 """)
 
 from bzrlib.hooks import Hooks
+from bzrlib.i18n import (
+    gettext,
+    gettext_per_paragraph,
+    install as i18n_install,
+    )
 # Compatibility - Option used to be in commands.
 from bzrlib.option import Option
 from bzrlib.plugin import disable_plugins, load_plugins
@@ -408,6 +413,7 @@
     takes_options = []
     encoding_type = 'strict'
     invoked_as = None
+    l10n = True
 
     hidden = False
 
@@ -486,8 +492,17 @@
             message explaining how to obtain full help.
         """
         doc = self.help()
-        if not doc:
-            doc = "No help for this command."
+        if doc:
+            # Note: If self.gettext() translates ':Usage:\n', the section will
+            # be shown after "Description" section and we don't want to
+            # translate the usage string.
+            # Though, bzr export-pot don't exports :Usage: section and it must
+            # not be translated.
+            if self.l10n:
+                i18n_install()  # Install i18n only for get_help_text for now.
+                doc = self.gettext(doc)
+        else:
+            doc = gettext("No help for this command.")
 
         # Extract the summary (purpose) and sections out from the text
         purpose,sections,order = self._get_help_parts(doc)
@@ -500,11 +515,11 @@
 
         # The header is the purpose and usage
         result = ""
-        result += ':Purpose: %s\n' % purpose
+        result += gettext(':Purpose: %s') % (purpose,) + '\n'
         if usage.find('\n') >= 0:
-            result += ':Usage:\n%s\n' % usage
+            result += gettext(':Usage:\n%s') % (usage,) + '\n'
         else:
-            result += ':Usage:   %s\n' % usage
+            result += gettext(':Usage:   %s') % (usage,) + '\n'
         result += '\n'
 
         # Add the options
@@ -512,7 +527,8 @@
         # XXX: optparse implicitly rewraps the help, and not always perfectly,
         # so we get <https://bugs.launchpad.net/bzr/+bug/249908>.  -- mbp
         # 20090319
-        options = option.get_optparser(self.options()).format_option_help()
+        parser = option.get_optparser(self.options())
+        options = parser.format_option_help()
         # FIXME: According to the spec, ReST option lists actually don't
         # support options like --1.14 so that causes syntax errors (in Sphinx
         # at least).  As that pattern always appears in the commands that
@@ -522,10 +538,7 @@
         if not plain and options.find('  --1.14  ') != -1:
             options = options.replace(' format:\n', ' format::\n\n', 1)
         if options.startswith('Options:'):
-            result += ':' + options
-        elif options.startswith('options:'):
-            # Python 2.4 version of optparse
-            result += ':Options:' + options[len('options:'):]
+            result += gettext(':Options:%s') % (options[len('options:'):],)
         else:
             result += options
         result += '\n'
@@ -536,26 +549,26 @@
             if sections.has_key(None):
                 text = sections.pop(None)
                 text = '\n  '.join(text.splitlines())
-                result += ':%s:\n  %s\n\n' % ('Description',text)
+                result += gettext(':Description:\n  %s') % (text,) + '\n\n'
 
             # Add the custom sections (e.g. Examples). Note that there's no need
             # to indent these as they must be indented already in the source.
             if sections:
                 for label in order:
-                    if sections.has_key(label):
-                        result += ':%s:\n%s\n' % (label,sections[label])
+                    if label in sections:
+                        result += ':%s:\n%s\n' % (label, sections[label])
                 result += '\n'
         else:
-            result += ("See bzr help %s for more details and examples.\n\n"
+            result += (gettext("See bzr help %s for more details and examples.\n\n")
                 % self.name())
 
         # Add the aliases, source (plug-in) and see also links, if any
         if self.aliases:
-            result += ':Aliases:  '
+            result += gettext(':Aliases:  ')
             result += ', '.join(self.aliases) + '\n'
         plugin_name = self.plugin_name()
         if plugin_name is not None:
-            result += ':From:     plugin "%s"\n' % plugin_name
+            result += gettext(':From:     plugin "%s"\n') % plugin_name
         see_also = self.get_see_also(additional_see_also)
         if see_also:
             if not plain and see_also_as_links:
@@ -567,11 +580,10 @@
                         see_also_links.append(item)
                     else:
                         # Use a Sphinx link for this entry
-                        link_text = ":doc:`%s <%s-help>`" % (item, item)
+                        link_text = gettext(":doc:`%s <%s-help>`") % (item, item)
                         see_also_links.append(link_text)
                 see_also = see_also_links
-            result += ':See also: '
-            result += ', '.join(see_also) + '\n'
+            result += gettext(':See also: %s') % ', '.join(see_also) + '\n'
 
         # If this will be rendered as plain text, convert it
         if plain:
@@ -658,13 +670,14 @@
     def run_argv_aliases(self, argv, alias_argv=None):
         """Parse the command line and run with extra aliases in alias_argv."""
         args, opts = parse_args(self, argv, alias_argv)
+        self._setup_outf()
 
         # Process the standard options
         if 'help' in opts:  # e.g. bzr add --help
-            sys.stdout.write(self.get_help_text())
+            self.outf.write(self.get_help_text())
             return 0
         if 'usage' in opts:  # e.g. bzr add --usage
-            sys.stdout.write(self.get_help_text(verbose=False))
+            self.outf.write(self.get_help_text(verbose=False))
             return 0
         trace.set_verbosity_level(option._verbosity_level)
         if 'verbose' in self.supported_std_options:
@@ -685,8 +698,6 @@
         all_cmd_args = cmdargs.copy()
         all_cmd_args.update(cmdopts)
 
-        self._setup_outf()
-
         try:
             return self.run(**all_cmd_args)
         finally:
@@ -751,6 +762,14 @@
             return None
         return getdoc(self)
 
+    def gettext(self, message):
+        """Returns the gettext function used to translate this command's help.
+
+        Commands provided by plugins should override this to use their
+        own i18n system.
+        """
+        return gettext_per_paragraph(message)
+
     def name(self):
         """Return the canonical name for this command.
 
@@ -1041,8 +1060,8 @@
     argv = _specified_or_unicode_argv(argv)
     trace.mutter("bzr arguments: %r", argv)
 
-    opt_lsprof = opt_profile = opt_no_plugins = opt_builtin =  \
-                opt_no_aliases = False
+    opt_lsprof = opt_profile = opt_no_plugins = opt_builtin = \
+            opt_no_l10n = opt_no_aliases = False
     opt_lsprof_file = opt_coverage_dir = None
 
     # --no-plugins is handled specially at a very early stage. We need
@@ -1065,6 +1084,8 @@
             opt_no_plugins = True
         elif a == '--no-aliases':
             opt_no_aliases = True
+        elif a == '--no-l10n':
+            opt_no_l10n = True
         elif a == '--builtin':
             opt_builtin = True
         elif a == '--concurrency':
@@ -1106,6 +1127,8 @@
 
     cmd = argv.pop(0)
     cmd_obj = get_cmd_object(cmd, plugins_override=not opt_builtin)
+    if opt_no_l10n:
+        cmd.l10n = False
     run = cmd_obj.run_argv_aliases
     run_argv = [argv, alias_argv]
 

=== modified file 'bzrlib/export_pot.py'
--- bzrlib/export_pot.py	2011-05-12 12:19:35 +0000
+++ bzrlib/export_pot.py	2011-06-23 16:06:27 +0000
@@ -76,10 +76,12 @@
            'msgid %s\n' % _normalize(s) +
            'msgstr ""\n')
 
-def _poentry_per_paragraph(outf, path, lineno, msgid):
+def _poentry_per_paragraph(outf, path, lineno, msgid, filter=lambda x: False):
     # TODO: How to split long help?
     paragraphs = msgid.split('\n\n')
     for p in paragraphs:
+        if filter(p):
+            continue
         _poentry(outf, path, lineno, p)
         lineno += p.count('\n') + 2
 
@@ -145,7 +147,7 @@
                      'help of %r option of %r command' % (name, cmd.name()))
 
 
-def _write_command_help(outf, cmd_name, cmd):
+def _write_command_help(outf, cmd):
     path = inspect.getfile(cmd.__class__)
     if path.endswith('.pyc'):
         path = path[:-1]
@@ -155,9 +157,16 @@
     lineno = offsets[cmd.__doc__]
     doc = inspect.getdoc(cmd)
 
-    _poentry_per_paragraph(outf, path, lineno, doc)
+    def filter(p):
+        # ':Usage:' has special meaning in help topics.
+        # This is usage example of command and should not be translated.
+        if p.splitlines()[0] == ':Usage:':
+            return True
+
+    _poentry_per_paragraph(outf, path, lineno, doc, filter)
     _command_options(outf, path, cmd)
 
+
 def _command_helps(outf):
     """Extract docstrings from path.
 
@@ -172,7 +181,7 @@
         if command.hidden:
             continue
         note("Exporting messages from builtin command: %s", cmd_name)
-        _write_command_help(outf, cmd_name, command)
+        _write_command_help(outf, command)
 
     plugin_path = plugin.get_core_plugin_path()
     core_plugins = glob(plugin_path + '/*/__init__.py')
@@ -189,7 +198,7 @@
             continue
         note("Exporting messages from plugin command: %s in %s",
              cmd_name, command.plugin_name())
-        _write_command_help(outf, cmd_name, command)
+        _write_command_help(outf, command)
 
 
 def _error_messages(outf):

=== modified file 'bzrlib/help.py'
--- bzrlib/help.py	2011-05-11 16:52:02 +0000
+++ bzrlib/help.py	2011-06-23 16:06:27 +0000
@@ -22,7 +22,6 @@
 # TODO: `help commands --all` should show hidden commands
 
 import sys
-import textwrap
 
 from bzrlib import (
     commands as _mod_commands,
@@ -30,6 +29,7 @@
     help_topics,
     osutils,
     plugin,
+    utextwrap,
     )
 
 
@@ -96,7 +96,7 @@
         else:
             firstline = ''
         helpstring = '%-*s %s%s' % (max_name, cmd_name, firstline, plugin_name)
-        lines = textwrap.wrap(
+        lines = utextwrap.wrap(
             helpstring, subsequent_indent=indent,
             width=width,
             break_long_words=False)

=== modified file 'bzrlib/help_topics/__init__.py'
--- bzrlib/help_topics/__init__.py	2010-11-06 10:55:58 +0000
+++ bzrlib/help_topics/__init__.py	2011-06-23 16:06:27 +0000
@@ -316,6 +316,7 @@
 --builtin      Use the built-in version of a command, not the plugin version.
                This does not suppress other plugin effects.
 --no-plugins   Do not process any plugins.
+--no-l10n      Do not translate messages.
 --concurrency  Number of processes that can be run concurrently (selftest).
 
 --profile      Profile execution using the hotshot profiler.

=== modified file 'bzrlib/i18n.py'
--- bzrlib/i18n.py	2011-05-27 21:38:33 +0000
+++ bzrlib/i18n.py	2011-06-23 16:06:27 +0000
@@ -75,7 +75,7 @@
 
 def uninstall():
     global _translation
-    _translation = _null_translation
+    _translation = _gettext.NullTranslations()
 
 
 def _get_locale_dir():

=== modified file 'bzrlib/tests/test_export_pot.py'
--- bzrlib/tests/test_export_pot.py	2011-05-11 17:44:45 +0000
+++ bzrlib/tests/test_export_pot.py	2011-06-23 16:06:27 +0000
@@ -18,10 +18,14 @@
 import textwrap
 
 from bzrlib import (
+    commands,
     export_pot,
     tests,
     )
 
+import re
+
+
 class TestEscape(tests.TestCase):
 
     def test_simple_escape(self):
@@ -145,3 +149,45 @@
                 "EGG\\n"
                 msgstr ""\n
                 ''')
+
+
+class TestExportCommandHelp(PoEntryTestCase):
+
+    def test_command_help(self):
+
+        class cmd_Demo(commands.Command):
+            __doc__ = """A sample command.
+
+            :Usage:
+                bzr demo
+
+            :Examples:
+                Example 1::
+
+                    cmd arg1
+
+            Blah Blah Blah
+            """
+
+        export_pot._write_command_help(self._outf, cmd_Demo())
+        result = self._outf.getvalue()
+        # We don't concern abount filename and lineno here.
+        result = re.sub(r'^#: [^\n]+\n', '', result, flags=re.MULTILINE)
+
+        self.assertEqualDiff(
+                'msgid "A sample command."\n'
+                'msgstr ""\n'
+                '\n'                # :Usage: should not be translated.
+                'msgid ""\n'
+                '":Examples:\\n"\n'
+                '"    Example 1::"\n'
+                'msgstr ""\n'
+                '\n'
+                'msgid "        cmd arg1"\n'
+                'msgstr ""\n'
+                '\n'
+                'msgid "Blah Blah Blah"\n'
+                'msgstr ""\n'
+                '\n',
+                result
+                )

=== modified file 'bzrlib/tests/test_help.py'
--- bzrlib/tests/test_help.py	2011-01-12 01:01:53 +0000
+++ bzrlib/tests/test_help.py	2011-06-23 16:06:27 +0000
@@ -22,10 +22,14 @@
     errors,
     help,
     help_topics,
+    i18n,
     plugin,
     tests,
     )
 
+from bzrlib.tests.test_i18n import ZzzTranslations
+import re
+
 
 class TestHelp(tests.TestCase):
 
@@ -295,6 +299,161 @@
             '  Blah blah blah.\n\n')
 
 
+class ZzzTranslationsForDoc(ZzzTranslations):
+
+    _section_pat = re.compile(':\w+:\\n\\s+')
+    _indent_pat = re.compile('\\s+')
+
+    def zzz(self, s):
+        m = self._section_pat.match(s)
+        if m is None:
+            m = self._indent_pat.match(s)
+        if m:
+            return u'%szz{{%s}}' % (m.group(0), s[m.end():])
+        return u'zz{{%s}}' % s
+
+
+class TestCommandHelpI18n(tests.TestCase):
+    """Tests for help on translated commands."""
+
+    def setUp(self):
+        super(TestCommandHelpI18n, self).setUp()
+        self.overrideAttr(i18n, '_translation', ZzzTranslationsForDoc())
+
+    def test_command_help_includes_see_also(self):
+        class cmd_WithSeeAlso(commands.Command):
+            __doc__ = """A sample command."""
+            _see_also = ['foo', 'bar']
+        cmd = cmd_WithSeeAlso()
+        helptext = cmd.get_help_text()
+        self.assertEndsWith(
+            helptext,
+            '  -v, --verbose  Display more information.\n'
+            '  -q, --quiet    Only display errors and warnings.\n'
+            '  -h, --help     Show help message.\n'
+            '}}\n'
+            'zz{{:See also: bar, foo}}\n')
+
+    def test_get_help_text(self):
+        """Commands have a get_help_text method which returns their help."""
+        class cmd_Demo(commands.Command):
+            __doc__ = """A sample command."""
+        cmd = cmd_Demo()
+        helptext = cmd.get_help_text()
+        self.assertStartsWith(helptext,
+            'zz{{:Purpose: zz{{A sample command.}}}}\n'
+            'zz{{:Usage:   bzr Demo}}\n')
+        self.assertEndsWith(helptext,
+            '  -h, --help     Show help message.\n}}\n')
+
+    def test_command_with_additional_see_also(self):
+        class cmd_WithSeeAlso(commands.Command):
+            __doc__ = """A sample command."""
+            _see_also = ['foo', 'bar']
+        cmd = cmd_WithSeeAlso()
+        helptext = cmd.get_help_text(['gam'])
+        self.assertEndsWith(
+            helptext,
+            '  -v, --verbose  Display more information.\n'
+            '  -q, --quiet    Only display errors and warnings.\n'
+            '  -h, --help     Show help message.\n'
+            '}}\n'
+            'zz{{:See also: bar, foo, gam}}\n')
+
+    def test_command_only_additional_see_also(self):
+        class cmd_WithSeeAlso(commands.Command):
+            __doc__ = """A sample command."""
+        cmd = cmd_WithSeeAlso()
+        helptext = cmd.get_help_text(['gam'])
+        self.assertEndsWith(
+            helptext,
+            'zz{{:Options:\n'
+            '  --usage        Show usage message and options.\n'
+            '  -v, --verbose  Display more information.\n'
+            '  -q, --quiet    Only display errors and warnings.\n'
+            '  -h, --help     Show help message.\n'
+            '}}\n'
+            'zz{{:See also: gam}}\n')
+
+
+    def test_help_custom_section_ordering(self):
+        """Custom descriptive sections should remain in the order given."""
+        class cmd_Demo(commands.Command):
+            __doc__ = """A sample command.
+ 
+            Blah blah blah.
+
+            :Formats:
+              Interesting stuff about formats.
+
+            :Examples:
+              Example 1::
+ 
+                cmd arg1
+
+            :Tips:
+              Clever things to keep in mind.
+            """
+        cmd = cmd_Demo()
+        helptext = cmd.get_help_text()
+        self.assertEqualDiff(
+            helptext,
+            'zz{{:Purpose: zz{{A sample command.}}}}\n'
+            'zz{{:Usage:   bzr Demo}}\n'
+            '\n'
+            'zz{{:Options:\n'
+            '  --usage        Show usage message and options.\n'
+            '  -v, --verbose  Display more information.\n'
+            '  -q, --quiet    Only display errors and warnings.\n'
+            '  -h, --help     Show help message.\n'
+            '}}\n'
+            'Description:\n'
+            '  zz{{zz{{Blah blah blah.}}}}\n'
+            '\n'
+            'Formats:\n'
+            '  zz{{Interesting stuff about formats.}}\n'
+            '\n'
+            'Examples:\n'
+            '  zz{{Example 1::}}\n'
+            '\n'
+            '    zz{{cmd arg1}}\n'
+            '\n'
+            'Tips:\n'
+            '  zz{{Clever things to keep in mind.}}\n'
+            '\n')
+
+    def test_help_text_custom_usage(self):
+        """Help text may contain a custom usage section."""
+        class cmd_Demo(commands.Command):
+            __doc__ = """A sample command.
+
+            :Usage:
+                cmd Demo [opts] args
+
+                cmd Demo -h
+
+            Blah blah blah.
+            """
+        cmd = cmd_Demo()
+        helptext = cmd.get_help_text()
+        self.assertEquals(helptext,
+            'zz{{:Purpose: zz{{A sample command.}}}}\n'
+            'zz{{:Usage:\n'
+            '    zz{{cmd Demo [opts] args}}\n'
+            '\n'
+            '    zz{{cmd Demo -h}}\n'
+            '}}\n'
+            '\n'
+            'zz{{:Options:\n'
+            '  --usage        Show usage message and options.\n'
+            '  -v, --verbose  Display more information.\n'
+            '  -q, --quiet    Only display errors and warnings.\n'
+            '  -h, --help     Show help message.\n'
+            '}}\n'
+            'Description:\n'
+            '  zz{{zz{{Blah blah blah.}}}}\n\n')
+
+
 class TestRegisteredTopic(TestHelp):
     """Tests for the RegisteredTopic class."""