Re: i18n docs
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. On 22 oct. 2011, at 00:10, Aymeric Augustin wrote: > 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. -- You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-developers@googlegroups.com. To unsubscribe from this group, send email to django-developers+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
Re: i18n docs
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Hi Aymeric, On 10/22/2011 05:02 AM, Aymeric Augustin wrote: > 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? 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- -- You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-developers@googlegroups.com. To unsubscribe from this group, send email to django-developers+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
Re: i18n docs
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. -- You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-developers@googlegroups.com. To unsubscribe from this group, send email to django-developers+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
