bpo-29755: Fixed the lgettext() family of functions in the gettext mo… · python/cpython@26cb465 (original) (raw)

`@@ -48,9 +48,10 @@ class-based API instead.

48

49

`.. function:: bind_textdomain_codeset(domain, codeset=None)

50

51

Bind the domain to codeset, changing the encoding of strings returned by the

52

`` -

:func:gettext family of functions. If codeset is omitted, then the current

53

binding is returned.

51

Bind the domain to codeset, changing the encoding of byte strings

52

`` +

returned by the :func:lgettext, :func:ldgettext, :func:lngettext

53

`` +

and :func:ldngettext functions.

54

If codeset is omitted, then the current binding is returned.

54

55

56

57

`.. function:: textdomain(domain=None)

`@@ -67,28 +68,14 @@ class-based API instead.

67

68

`` :func:_ in the local namespace (see examples below).

68

69

70

.. function:: lgettext(message)

71

-

72

`` -

Equivalent to :func:gettext, but the translation is returned in the

73

preferred system encoding, if no other encoding was explicitly set with

74

`` -

:func:bind_textdomain_codeset.

75

-

76

-

77

71

`.. function:: dgettext(domain, message)

78

72

79

`` -

Like :func:gettext, but look the message up in the specified domain.

80

-

81

-

82

.. function:: ldgettext(domain, message)

83

-

84

`` -

Equivalent to :func:dgettext, but the translation is returned in the

85

preferred system encoding, if no other encoding was explicitly set with

86

`` -

:func:bind_textdomain_codeset.

73

`` +

Like :func:.gettext, but look the message up in the specified domain.

87

74

88

75

89

76

`.. function:: ngettext(singular, plural, n)

90

77

91

`` -

Like :func:gettext, but consider plural forms. If a translation is found,

78

`` +

Like :func:.gettext, but consider plural forms. If a translation is found,

92

79

` apply the plural formula to n, and return the resulting message (some

93

80

` languages have more than two plural forms). If no translation is found, return

94

81

` singular if n is 1; return plural otherwise.

`@@ -101,24 +88,33 @@ class-based API instead.

101

88

` formulas for a variety of languages.

102

89

103

90

104

.. function:: lngettext(singular, plural, n)

105

-

106

`` -

Equivalent to :func:ngettext, but the translation is returned in the

107

preferred system encoding, if no other encoding was explicitly set with

108

`` -

:func:bind_textdomain_codeset.

109

-

110

-

111

91

`.. function:: dngettext(domain, singular, plural, n)

112

92

113

93

`` Like :func:ngettext, but look the message up in the specified domain.

114

94

115

95

96

.. function:: lgettext(message)

97

.. function:: ldgettext(domain, message)

98

.. function:: lngettext(singular, plural, n)

116

99

`.. function:: ldngettext(domain, singular, plural, n)

117

100

118

`` -

Equivalent to :func:dngettext, but the translation is returned in the

119

preferred system encoding, if no other encoding was explicitly set with

101


 Equivalent to the corresponding functions without the ``l`` prefix

102

`` +

(:func:.gettext, :func:dgettext, :func:ngettext and :func:dngettext),

103

but the translation is returned as a byte string encoded in the preferred

104

system encoding if no other encoding was explicitly set with

120

105

`` :func:bind_textdomain_codeset.

121

106

107

.. warning::

108

+

109

These functions should be avoided in Python 3, because they return

110

encoded bytes. It's much better to use alternatives which return

111

Unicode strings instead, since most Python applications will want to

112

manipulate human readable text as strings instead of bytes. Further,

113

it's possible that you may get unexpected Unicode-related exceptions

114

if there are encoding problems with the translated strings. It is

115


 possible that the ``l*()`` functions will be deprecated in future Python

116

versions due to their inherent problems and limitations.

117

+

122

118

123

119

`` Note that GNU :program:gettext also defines a :func:dcgettext method, but

124

120

`this was deemed not useful and so it is currently unimplemented.

`@@ -179,8 +175,9 @@ class can also install themselves in the built-in namespace as the function

179

175

` names are cached. The actual class instantiated is either class_ if

180

176

`` provided, otherwise :class:GNUTranslations. The class's constructor must

181

177

`` take a single :term:file object argument. If provided, codeset will change

182

`` -

the charset used to encode translated strings in the :meth:lgettext and

183

`` -

:meth:lngettext methods.

178

the charset used to encode translated strings in the

179

`` +

:meth:~NullTranslations.lgettext and :meth:~NullTranslations.lngettext

180

methods.

184

181

185

182

` If multiple files are found, later files are used as fallbacks for earlier ones.

186

183

`` To allow setting the fallback, :func:copy.copy is used to clone each

`` @@ -250,26 +247,29 @@ are the methods of :class:NullTranslations:

250

247

251

248

` .. method:: gettext(message)

252

249

253

`` -

If a fallback has been set, forward :meth:gettext to the fallback.

254

Otherwise, return the translated message. Overridden in derived classes.

255

-

256

-

257

.. method:: lgettext(message)

258

-

259

`` -

If a fallback has been set, forward :meth:lgettext to the fallback.

260

Otherwise, return the translated message. Overridden in derived classes.

250

`` +

If a fallback has been set, forward :meth:.gettext to the fallback.

251

Otherwise, return message. Overridden in derived classes.

261

252

262

253

263

254

` .. method:: ngettext(singular, plural, n)

264

255

265

256

`` If a fallback has been set, forward :meth:ngettext to the fallback.

266

Otherwise, return the translated message. Overridden in derived classes.

257

Otherwise, return singular if n is 1; return plural otherwise.

258

Overridden in derived classes.

267

259

268

260

261

.. method:: lgettext(message)

269

262

` .. method:: lngettext(singular, plural, n)

270

263

271

`` -

If a fallback has been set, forward :meth:lngettext to the fallback.

272

Otherwise, return the translated message. Overridden in derived classes.

264

`` +

Equivalent to :meth:.gettext and :meth:ngettext, but the translation

265

is returned as a byte string encoded in the preferred system encoding

266

`` +

if no encoding was explicitly set with :meth:set_output_charset.

267

Overridden in derived classes.

268

+

269

.. warning::

270

+

271

These methods should be avoided in Python 3. See the warning for the

272

`` +

:func:lgettext function.

273

274

275

` .. method:: info()

`` @@ -279,32 +279,28 @@ are the methods of :class:NullTranslations:

279

280

` .. method:: charset()

281

282

`` -

Return the "protected" :attr:_charset variable, which is the encoding of

283

the message catalog file.

282

Return the encoding of the message catalog file.

284

283

285

284

286

285

` .. method:: output_charset()

287

286

288

`` -

Return the "protected" :attr:_output_charset variable, which defines the

289

`` -

encoding used to return translated messages in :meth:lgettext and

290

`` -

:meth:lngettext.

287

`` +

Return the encoding used to return translated messages in :meth:.lgettext

288

`` +

and :meth:.lngettext.

291

289

292

290

293

291

` .. method:: set_output_charset(charset)

294

292

295

`` -

Change the "protected" :attr:_output_charset variable, which defines the

296

encoding used to return translated messages.

293

Change the encoding used to return translated messages.

297

294

298

295

299

296

` .. method:: install(names=None)

300

297

301

`` -

This method installs :meth:self.gettext into the built-in namespace,

298

`` +

This method installs :meth:.gettext into the built-in namespace,

302

299

``` binding it to _.


`303`

`300`

``

`304`

`301`

` If the *names* parameter is given, it must be a sequence containing the

`

`305`

`302`

` names of functions you want to install in the builtins namespace in

`

`306`

``

``` -

addition to :func:`_`. Supported names are ``'gettext'`` (bound to

307


:meth:`self.gettext`), ``'ngettext'`` (bound to :meth:`self.ngettext`),

303


 addition to :func:`_`. Supported names are ``'gettext'``, ``'ngettext'``,

308

304

``` 'lgettext' and 'lngettext'.

```

309

305

310

306

` Note that this is only one way, albeit the most convenient way, to make

`` @@ -349,49 +345,52 @@ If the :file:.mo file's magic number is invalid, the major version number is

349

345

`unexpected, or if other problems occur while reading the file, instantiating a

350

346

`` :class:GNUTranslations class can raise :exc:OSError.

351

347

352

The following methods are overridden from the base class implementation:

353

-

348

.. class:: GNUTranslations

354

349

355

.. method:: GNUTranslations.gettext(message)

350

The following methods are overridden from the base class implementation:

356

351

357

Look up the message id in the catalog and return the corresponding message

358

string, as a Unicode string. If there is no entry in the catalog for the

359

message id, and a fallback has been set, the look up is forwarded to the

360

`` -

fallback's :meth:gettext method. Otherwise, the message id is returned.

352

.. method:: gettext(message)

361

353

354

Look up the message id in the catalog and return the corresponding message

355

string, as a Unicode string. If there is no entry in the catalog for the

356

message id, and a fallback has been set, the look up is forwarded to the

357

`` +

fallback's :meth:~NullTranslations.gettext method. Otherwise, the

358

message id is returned.

362

359

363

.. method:: GNUTranslations.lgettext(message)

364

360

365

`` -

Equivalent to :meth:gettext, but the translation is returned as a

366

bytestring encoded in the selected output charset, or in the preferred system

367

`` -

encoding if no encoding was explicitly set with :meth:set_output_charset.

361

.. method:: ngettext(singular, plural, n)

368

362

363

Do a plural-forms lookup of a message id. singular is used as the message id

364

for purposes of lookup in the catalog, while n is used to determine which

365

plural form to use. The returned message string is a Unicode string.

369

366

370

.. method:: GNUTranslations.ngettext(singular, plural, n)

367

If the message id is not found in the catalog, and a fallback is specified,

368

`` +

the request is forwarded to the fallback's :meth:~NullTranslations.ngettext

369

method. Otherwise, when n is 1 singular is returned, and plural is

370

returned in all other cases.

371

372

Do a plural-forms lookup of a message id. singular is used as the message id

373

for purposes of lookup in the catalog, while n is used to determine which

374

plural form to use. The returned message string is a Unicode string.

372

Here is an example::

375

373

376

If the message id is not found in the catalog, and a fallback is specified, the

377

`` -

request is forwarded to the fallback's :meth:ngettext method. Otherwise, when

378

n is 1 singular is returned, and plural is returned in all other cases.

374

n = len(os.listdir('.'))

375

cat = GNUTranslations(somefile)

376

message = cat.ngettext(

377

'There is %(num)d file in this directory',

378

'There are %(num)d files in this directory',

379

n) % {'num': n}

379

380

Here is an example::

381

382

n = len(os.listdir('.'))

383

cat = GNUTranslations(somefile)

384

message = cat.ngettext(

385

'There is %(num)d file in this directory',

386

'There are %(num)d files in this directory',

387

n) % {'num': n}

382

.. method:: lgettext(message)

383

.. method:: lngettext(singular, plural, n)

388

384

385

`` +

Equivalent to :meth:.gettext and :meth:.ngettext, but the translation

386

is returned as a byte string encoded in the preferred system encoding

387

if no encoding was explicitly set with

388

`` +

:meth:~NullTranslations.set_output_charset.

389

390

.. method:: GNUTranslations.lngettext(singular, plural, n)

390

.. warning::

391

392

`` -

Equivalent to :meth:gettext, but the translation is returned as a

393

bytestring encoded in the selected output charset, or in the preferred system

394

`` -

encoding if no encoding was explicitly set with :meth:set_output_charset.

392

These methods should be avoided in Python 3. See the warning for the

393

`` +

:func:lgettext function.

395

394

396

395

397

396

`Solaris message catalog support

`@@ -509,7 +508,7 @@ module::

509

508

510

509

` import gettext

511

510

` t = gettext.translation('spam', '/usr/share/locale')

512

_ = t.lgettext

511

_ = t.gettext

513

512

514

513

515

514

`Localizing your application