Code

Opened 5 years ago

Closed 4 years ago

Last modified 3 years ago

#10260 closed (fixed)

i18n documentation refactoring

Reported by: ramiro Owned by: ramiro
Component: Documentation Version: master
Severity: Keywords: l10n i18n translation message files localization intrnationalization
Cc: mtredinnick, gonz, jezdez Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

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 5 years ago.
10260-i18n_docs_refactor-r11173.diff (94.4 KB) - added by ramiro 5 years ago.
Patch updated to include changes from r11103 and r11164 plus further modifications
10260-post-r11237.diff (94.8 KB) - added by ramiro 5 years ago.
Patch updated with changes introduced in r11237
10260-post-r11964.diff (100.3 KB) - added by ramiro 4 years ago.
Patch updated to trunk state after r11964 (locale aware formatting)
10260-post-r11964.2.diff (101.1 KB) - added by ramiro 4 years ago.
More enhancements, includes fix for #12449
10260-i18n-docs-rf-r12194.diff (104.7 KB) - added by ramiro 4 years ago.
Updated patch
10260-i18n-docs-rf-r12229.diff (104.7 KB) - added by ramiro 4 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 4 years ago.
Patch for 1.1.x branch as of r12229.
10260-i18n-docs-rf-r12336.diff (105.5 KB) - added by ramiro 4 years ago.
Updated to trunk post-r12296, also added a fix for #11793.

Download all attachments as: .zip

Change History (22)

Changed 5 years ago by ramiro

comment:1 Changed 5 years ago by ramiro

  • Has patch set
  • Keywords l10n i18n translation message files localization intrnationalization added
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

comment:2 Changed 5 years ago by ramiro

  • Owner changed from nobody to ramiro

comment:3 Changed 5 years ago by Alex

  • Triage Stage changed from Unreviewed to Accepted

comment:4 Changed 5 years ago by mtredinnick

  • Cc mtredinnick added

I'll review this when I get a chance.

comment:5 Changed 5 years ago by ramiro

See also #7283

Changed 5 years ago by ramiro

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

comment:6 in reply to: ↑ description Changed 5 years ago by ramiro

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 Changed 5 years ago by anonymous

  • Cc gonz added

Changed 5 years ago by ramiro

Patch updated with changes introduced in r11237

Changed 4 years ago by ramiro

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

Changed 4 years ago by ramiro

More enhancements, includes fix for #12449

comment:8 Changed 4 years ago by jezdez

  • Cc jezdez added

Changed 4 years ago by ramiro

Updated patch

comment:9 Changed 4 years ago by ramiro

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.

Changed 4 years ago by ramiro

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

Changed 4 years ago by ramiro

Patch for 1.1.x branch as of r12229.

Changed 4 years ago by ramiro

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

comment:10 Changed 4 years ago by russellm

  • milestone set to 1.2

comment:11 Changed 4 years ago by jezdez

  • Resolution set to fixed
  • Status changed from new to closed

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

comment:12 Changed 4 years ago by jezdez

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

Partial backport of r12440.

comment:13 Changed 3 years ago by jacob

  • milestone 1.2 deleted

Milestone 1.2 deleted

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.