Opened 15 years ago

Closed 14 years ago

Last modified 12 years ago

#10260 closed (fixed)

i18n documentation refactoring

Reported by: Ramiro Morales Owned by: Ramiro Morales
Component: Documentation Version: dev
Severity: Keywords: l10n i18n translation message files localization intrnationalization
Cc: Malcolm Tredinnick, Gonzalo Saavedra, Jannis Leidel Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The attached code reshuffles and modifies the internationalization docs in the following way:

  • Divided the documentation in: An introductory document (with links to the other docs and to a couple of external resources) plus thee documents describing different tasks: internationalization, localization and deployment.
  • i18n doc: Consolidated the sections that talk about lazy translations and put the Pluralization section before them.
  • Put the sections about JavaScript on the i18n doc and at the same level as the Python and template translatable string marking up sections, only a section about how to extract and compile message catalogs from JS has been kept in the l10n doc.
  • Removed the content about translating Django itself that was scattered all over the document(s). Because of that it wasn't helpful to the minor audience interested in it and confused things for the major audience: people dealing with apps i18n. Moved the non-redundant text to the already existing relevant internals/contributing.txt section.
  • Moved text about how to create a minimal Django translation (to be able to activate an app translation to a given language) from the locale middleware notes (now in the deployment doc) to the l10n doc, leaving only a small note and a reference. The description of Django technical messages got moved to internals/contributing.txt.
  • Put the gettext on win32 section on the l10n doc.
  • Small typo fixes.
  • Unfied treatment given to .po files. They are now refered to as message files in all documents. The section about creating/updating these files from JavaScript code refered to them as message catalogs, it wasn´t wrong but was inconsistent and could be confused with a different thing: the data served by the javascript_catalog (the section describing it does even calls it message catalogs)

Things for further thought:

  • What to do with the Using translations in your own projects section (now on the l10n doc)? Currently it's a mix of things (duplicate info, app architecture, integration and deployment advice).
  • Move some content to the howto/ Django doc sub-tree?

Attachments (9)

i18n-doc-rf.diff (87.3 KB ) - added by Ramiro Morales 15 years ago.
10260-i18n_docs_refactor-r11173.diff (94.4 KB ) - added by Ramiro Morales 15 years ago.
Patch updated to include changes from r11103 and r11164 plus further modifications
10260-post-r11237.diff (94.8 KB ) - added by Ramiro Morales 15 years ago.
Patch updated with changes introduced in r11237
10260-post-r11964.diff (100.3 KB ) - added by Ramiro Morales 14 years ago.
Patch updated to trunk state after r11964 (locale aware formatting)
10260-post-r11964.2.diff (101.1 KB ) - added by Ramiro Morales 14 years ago.
More enhancements, includes fix for #12449
10260-i18n-docs-rf-r12194.diff (104.7 KB ) - added by Ramiro Morales 14 years ago.
Updated patch
10260-i18n-docs-rf-r12229.diff (104.7 KB ) - added by Ramiro Morales 14 years ago.
Patch for trunk updated to r12229 (solve merge conflict with r12213).
10260-i18n-docs-rf-1.1.x-r12229.diff (97.4 KB ) - added by Ramiro Morales 14 years ago.
Patch for 1.1.x branch as of r12229.
10260-i18n-docs-rf-r12336.diff (105.5 KB ) - added by Ramiro Morales 14 years ago.
Updated to trunk post-r12296, also added a fix for #11793.

Download all attachments as: .zip

Change History (22)

by Ramiro Morales, 15 years ago

Attachment: i18n-doc-rf.diff added

comment:1 by Ramiro Morales, 15 years ago

Has patch: set
Keywords: l10n i18n translation message files localization intrnationalization added

comment:2 by Ramiro Morales, 15 years ago

Owner: changed from nobody to Ramiro Morales

comment:3 by Alex Gaynor, 15 years ago

Triage Stage: UnreviewedAccepted

comment:4 by Malcolm Tredinnick, 15 years ago

Cc: Malcolm Tredinnick added

I'll review this when I get a chance.

comment:5 by Ramiro Morales, 15 years ago

See also #7283

by Ramiro Morales, 15 years ago

Patch updated to include changes from r11103 and r11164 plus further modifications

in reply to:  description comment:6 by Ramiro Morales, 15 years ago

Replying to ramiro:

Things for further thought:

  • What to do with the Using translations in your own projects section (now on the l10n doc)? Currently it's a mix of things (duplicate info, app architecture, integration and deployment advice).
  • Move some content to the howto/ Django doc sub-tree?

10260-i18n_docs_refactor-r11173.diff is an updated copy of the patch.

Note: The patch removes the topics/i18n.txt file and replaces it by a topics/i18n/ directory containing the internationalization.txt, localization.txt and deployment.txt documents.

This revision contains the following changes compared to the previous one:

  • It include changes from r11103 and r11164.
  • The Using translations in your own projects section was moved to a new topics/i18n.txt document.
  • The description of Django technical messages was moved to the Specialties of Django i18n section, an example was added.
  • The section about the algorithm used by Django to discover translations at runtime is included in two documents topics/i18n/deployment.txt and topics/i18n.txt.

comment:7 by anonymous, 15 years ago

Cc: Gonzalo Saavedra added

by Ramiro Morales, 15 years ago

Attachment: 10260-post-r11237.diff added

Patch updated with changes introduced in r11237

by Ramiro Morales, 14 years ago

Attachment: 10260-post-r11964.diff added

Patch updated to trunk state after r11964 (locale aware formatting)

by Ramiro Morales, 14 years ago

Attachment: 10260-post-r11964.2.diff added

More enhancements, includes fix for #12449

comment:8 by Jannis Leidel, 14 years ago

Cc: Jannis Leidel added

by Ramiro Morales, 14 years ago

Updated patch

comment:9 by Ramiro Morales, 14 years ago

Latest patch contains the following additional changes:

  • Added a note to the 1.2 release notes about the deprecation of technical message IDs previously used to specify date/time format localization.
  • Added a glossary of i18n terms plus cross links.

by Ramiro Morales, 14 years ago

Patch for trunk updated to r12229 (solve merge conflict with r12213).

by Ramiro Morales, 14 years ago

Patch for 1.1.x branch as of r12229.

by Ramiro Morales, 14 years ago

Updated to trunk post-r12296, also added a fix for #11793.

comment:10 by Russell Keith-Magee, 14 years ago

milestone: 1.2

comment:11 by Jannis Leidel, 14 years ago

Resolution: fixed
Status: newclosed

(In [12440]) Fixed #10260 - Refactored internationalization documentation. Thanks, Ramiro Morales.

comment:12 by Jannis Leidel, 14 years ago

(In [12449]) [1.1.X] Fixed #10260 - Refactored internationalization documentation. Thanks, Ramiro Morales.

Partial backport of r12440.

comment:13 by Jacob, 12 years ago

milestone: 1.2

Milestone 1.2 deleted

Note: See TracTickets for help on using tickets.
Back to Top