i18n docs

[Aymeric Augustin]

Hello,

Maybe it's just me, but I find the i18n docs quite confusing, and I often struggle to locate the information I need:
https://docs.djangoproject.com/en/1.3/topics/i18n/

For instance, I don't understand why:
- the index page immediately dives into gettext technicalities;
- /topics/i18n/localization/ describes how to write .po files and how to use the localization features of Django (USE_L10N), two seemingly unrelated topics;
- implementation details of i18n are split between /howto/i18n/ and /topics/i18n/deployment/.

In the context of my timezone support branch, I'd like to clarify all this.

I regard internationalization as the combination of three things:
1 - USE_I18N = translation, per language
=> translating text in code and templates -- USE_I18N is an unfortunate choice for the translation setting, but that's history)
2 - USE_L10N = localization, per country
=> formatting dates, times, numbers -- possibly currencies and units in the future
3 - USE_TZ = time zone, per region
=> converting datetimes

I think there should be an index page and one page for each of these three topics.

What do you think? Have I missed something?

Thanks,

--
Aymeric Augustin.

[Aymeric Augustin]

Hello,

On IRC, Bas Peschier pointed out that the current docs follow the "definitions" of i18n and l10n.

In fact, the code (in particular the settings) uses the "gettext" definitions while the docs use the more general "Wikipedia" definition, and confusion ensues.

For consistency, I think the docs should reflect the assumptions of the code. So I'm proposing the following clarification:

> Definitions
> ===========
>
> Different people give different meanings to the words "internationalization" and
> "localization".
>
> Django follows the definitions from the `GNU gettext documentation`_:
>
> * Internationalization means supporting multiple languages;
> * Localization means supporting multiple input and output formats.
>
> In short, internationalization is about text, localization is about data.
>
> The `Wikipedia article`_ and the `W3C Web Internationalization FAQ`_ have a
> different approach:
>
> * Internationalization means preparing the software for localization;
> * Localization means writing the translations and local data.
>
> From this point of view, internationalization is for developers, localization
> is for translators.
>
> Although the latter definition is more common and possibly more correct, Django
> sticks with the former. Developers being the primary audience, a thematic
> approach makes more sense. It's more consistent with the implementation too.
>
> .. _W3C Web Internationalization FAQ: http://www.w3.org/International/questions/qa-i18n
> .. _GNU gettext documentation: http://www.gnu.org/software/gettext/manual/gettext.html#Concepts
> .. _Wikipedia article: http://en.wikipedia.org/wiki/Internationalization_and_localization

Does this make sense?

--
Aymeric Augustin.

[Carl Meyer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Aymeric,

I'm an expert in neither internationalization nor localization, but I do
think that our code (in particular the highly user-visible bits like
settings) should use the same definitions as our docs, otherwise we're
just asking for confusion. And it's a lot easier to change the docs than
to make backwards-incompatible code changes. So unless there is a really
compelling reason to use the Wikipedia/W3C definitions, I agree with
your proposed change.

Carl
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk6i5rMACgkQ8W4rlRKtE2eMlACfQryWkcDVkM2dVi4aYML9fnOr
+NQAoIlH4rME4kYgw6S+/rCLsxfrxXsz
=8BtB
-----END PGP SIGNATURE-----

[Aymeric Augustin]

On 22 oct. 2011, at 17:52, Carl Meyer wrote:
> I'm an expert in neither internationalization nor localization, but I do
> think that our code (in particular the highly user-visible bits like
> settings) should use the same definitions as our docs, otherwise we're
> just asking for confusion. And it's a lot easier to change the docs than
> to make backwards-incompatible code changes. So unless there is a really
> compelling reason to use the Wikipedia/W3C definitions, I agree with
> your proposed change.

In fact, neither of my two emails was accurate :( I had misread the GNU gettext docs: they agree that internationalization = the developer's job and localization = the translator's job. This is absolutely counter-intuitive for someone like me who discovered Django's USE_I18N and USE_L10N first.

I've attempted to sidestep the issue in our docs by:
- calling USE_I18N-related stuff "translation" and USE_L10N-related "formatting",
- avoiding the words "internationalization" and "localization" as much as possible,
- warning that the names of the settings are historical.

In the process, I've proof-read all the i18n docs, edited them lightly, and removed some duplication (especially with the i18n howto). Given that I've moved files and chunks of text around, the result was hardly possible to review, so I committed it at r17026, after checking that I didn't lose any text.

Further improvements are certainly possible, feedback welcome.

Thanks,

--
Aymeric Augustin.