From b91fcb32f18389e9819609bd889aa85c1730ed76 Mon Sep 17 00:00:00 2001 From: James Carey Date: Tue, 24 Feb 2015 22:23:36 +0000 Subject: Update guideline doc of multiple use msg case There was confusion in a cinder review with respect to the case where a message is used both in a log and in an exception: https://review.openstack.org/#/c/155894/2 This update is to clarify the guidelines to help prevent similar confusion in the future. Change-Id: Ia26b4d3efafb8ad13c45e982a1be7aea176417e1 --- doc/source/guidelines.rst | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/source/guidelines.rst b/doc/source/guidelines.rst index 2377d64..a4a56c0 100644 --- a/doc/source/guidelines.rst +++ b/doc/source/guidelines.rst @@ -34,6 +34,27 @@ source code and pass it to the translation tool. * LOG.exception creates an ERROR level log, so when a marker function is used (see below) ``_LE()`` should be used. + +Using a Marker Function +======================= +The marker functions are used to mark the translatable strings in the +code. The strings are extracted into catalogs using a tool that +looks for these specific markers, so the function argument must just +be a string. + +For example: **do not do this**:: + + # WRONG + msg = _(variable_containing_msg) + w_msg = _LW(variable_warning_msg) + +Instead, use this style:: + + # RIGHT + msg = _('My message.') + w_msg = _LW('My warning message') + + Choosing a Marker Function ========================== @@ -64,10 +85,7 @@ than once, for the log call and the exception. In that case, ``_()`` must be used because the message is going to appear in an exception that may be presented to the user. -Examples --------- - -**Do not do this**:: +For example, **do not do this**:: # WRONG msg = _LE('There was an error.') @@ -84,7 +102,12 @@ Instead, use this style:: Except in the case above, ``_()`` should not be used for translating log messages. This avoids having the same string in two message catalogs, possibly translated differently by two different -translators. +translators. The log message will translate properly because when +the message is not found in the log specific catalog the ``_()`` +catalog will be used. + +If a common message is not being used, they should each be treated +separately with respect to choosing a marker function. For example, **do not do this**:: -- cgit v1.2.1