Il8n and l10n - Revision history

Blu256: Fixed wording and link

2022-04-21T16:01:56Z

Fixed wording and link

Blu256: Added programmer warning

2022-04-21T15:53:14Z

Added programmer warning

Blu256: Blu256 moved page Il8n and l10n (KDE3 Architecture) to Il8n and l10n: Simplify

2022-04-21T15:49:45Z

Blu256 moved page Il8n and l10n (KDE3 Architecture) to Il8n and l10n: Simplify

Blu256: -Applicable to TDE (redundant), categories to bottom

2022-04-21T15:49:30Z

-Applicable to TDE (redundant), categories to bottom

Blu256: /* Generating translations */ Addition

2021-09-13T16:45:33Z

Generating translations: Addition

Blu256: /* Generating translations */ minor fixes

2021-09-13T16:24:13Z

Generating translations: minor fixes

Blu256: Added misc. notes

2021-09-13T16:22:47Z

Added misc. notes

Blu256: Added Table of Contents

2021-08-22T21:27:23Z

Added Table of Contents

Blu256: Updated

2021-08-22T21:26:59Z

Updated

Show changes

imported>Eliddell: Created page with "Reaching a broad audience of users and developers requires that your software can be translated and otherwise shaped at runtime to be linguistically and culturally relevant to..."

2014-06-03T21:06:43Z

Created page with "Reaching a broad audience of users and developers requires that your software can be translated and otherwise shaped at runtime to be linguistically and culturally relevant to..."

New page

Reaching a broad audience of users and developers requires that your software can be translated and otherwise shaped at runtime to be linguistically and culturally relevant to whomever is sitting in front of the computer. This is the realm of localization and this tutorial steps you through what is needed to make your application localizable.

== What is Internationalization and Localization? ==

Internationalization, or i18n ('i', followed by 18 letters, then an 'n'), is the process of writing your application so that it can be run in any locale. This means taking into account such things as:
* textual messages that are displayed to the user
* data input from the user, files and other sources
* format of dates, numbers, currency, dates, etc.

Localization, or l10n ('l', followed by 10 characters, then an 'n'), is the process of taking an internationalized application and adapting it for a specific locale.

Generaly speaking, programmers internationalize their applications and translation teams localize them.

== Why is This Important? ==

KDE development happens primarily in English as this allows the broadest reach into the development and translation communities. However, English is not the primary language of most people on the planet. In fact, fewer than 8% of humanity speaks English and less than 5% speak it as their mother tongue. Even on the Internet, only 35% people who are online use English as their primary language and as more and more of the world gets wired this number is only decreasing. Additionally most languages, including 9 out of the 10 most common languages, use non-ASCII characters in their written form. It is easy to see, then, why it has become a necessity to provide localized software.

As an international project that spans the globe such localization is a core value within the KDE culture. In fact, while many KDE developers write their software in English they use the desktop in their native locale.

== Translatable Code Using i18n() ==

To ensure applications are ready to be localized they have to follow a few simple rules. All user-visible strings in the application should be translated before they are displayed on the user's screen, exceptions to this being debugging messages, configuration keys and similar types of text data.

KDE provides the <tt>KLocale</tt> class as part of <tt>libkdecore</tt> to facilitate the technical details of localization. KLocale makes it as easy as possible for developers to make their code i18n aware, but there are some things they need to be aware of so that applications are usable in other languages and countries.

Access to a global <tt>KLocale</tt> object is provided via <tt>KGlobal::locale()</tt>. This <tt>KLocale</tt> object is created automatically by <tt>KInstance</tt> and takes care of all user i18n related settings. It is deleted automatically on application exit.

Translations are made possible by the <tt>QString i18n(const char*)</tt> method which must wrap all strings that should be displayed. The QString returned by <tt>i18n()</tt> is the translated (if necessary) string. This makes creating translatable widgets as simple as in this example:

<syntaxhighlight lang="cpp-qt">
QPushButton* myButton = new QPushButton(i18n("Translate this!"), 0);</syntaxhighlight>

QString's native Unicode support ensures that all translations are represented correctly. All string handling done by your application should therefore use QString.

Tip: If the string to be translated contains any non-UTF8 characters, use the utf8() method to get a char*.

=== I18N_NOOP ===

The <tt>i18n()</tt> method requires that a <tt>KInstance</tt> (e.g. <tt>KApplication</tt>) has been created. For any strings that are created prior to this there is a macro provided: I18N_NOOP(). This allows one to mark strings that should be translated later as such.

When you want to actually translate the string at runtime, you still have to use i18n() with exactly the same string. I18N_NOOP() is typically used for strings given to KAboutData, because it is constructed before the KApplication and you can use i18n() only after the construction of the KApplication. Other than these special cases, it is always safe to use i18n() if you are sure that the code will be executed after construction of KApplication or some other KInstance.

=== Adding Context ===

There is an extended version of <tt>i18n()</tt> which takes two <tt>const char*</tt> arguments. The first argument is an additional contextual description of the second, translated string. The first string is used to find the proper corresponding translation at run-time and is shown to translators to help them understand the meaning of the string.

Use this variety of <tt>i18n()</tt> when the purpose of the text might be ambiguous without further context. For example, consider a context menu in a file manager with an entry called "View" which opens a viewer for the currently selected file. In this context "View" is a verb. However, the same application also may have a menu called "View" in the menubar. In that context "View" is a noun. In the English version of the application everything looks fine, but in most other languages one of the two "View" strings will be incorrect.

Additionally, translators sometimes need extra help in understanding what the text is actually referring to during the translation purpose. Use this form of i18n whenever the string to translate is short or the meaning is hard to discern when the context is not exactly known. For example:

<syntaxhighlight lang="cpp-qt">QString up = i18n("Go one directory up in the hierarchy", "Up");
QString relation = i18n("A person's name and their familial relationship to you.", "%1 is your %2").arg(name, relationship);</syntaxhighlight>

Note: There is also a I18N_NOOP2("context","text") macro for providing untranslated strings with a context.

=== Plurals ===

Plurals are handled differently from language to language. Many languages have different plurals for 2, 10, 20, 100, etc. When the string you want translated refers to more than one item, you must use the third form of <tt>i18n</tt>: <tt>QString i18n(const char* singular, const char* plural, int number)</tt>. For example:

<syntaxhighlight lang="cpp-qt">msgStr = i18n("Creating index file: 1 message done",
"Creating index file: %n messages done", num);</syntaxhighlight>

This form of <tt>i18n()</tt> gets expanded to as many cases as required by the user's language. In English, this is just two forms while in other languages it may be more depending on the value of the <tt>number</tt> parameter.

Note that this form should be used even if the string always refers to more than one item as languages use a singular form even when referring to a multiple (typically for 21, 31, etc.). This code:

<syntaxhighlight lang="cpp-qt">i18n("%1 files were deleted").arg(numFilesDeleted);</syntaxhighlight>

is therefore incorrect and should instead be:

<syntaxhighlight lang="cpp-qt">i18n("%1 files were deleted",
"%1 files were deleted",
numFilesDeleted).arg(numFilesDeleted);</syntaxhighlight>

== Formatting Dates and Numbers ==

When displaying a number to the user, your program must take care of the decimal separator, thousand separator and currency symbol (if any) being used. These symbols differ from region to region. In English speaking countries a dot (.) is used to separate the fractional part of a number, while in some European countries a comma (,) is used instead. Below is a short summary of functions that will help you format the numbers correctly, taking the local conventions into account for you.

{|
|+ Functions to Format Numbers
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Number || String || <pre>QString formatNumber( const QString & numStr )</pre>
|-
| Number || Integer, double || <pre>formatNumber( double num,
int precision = -1 )</pre>
|-
| Money || String || <pre>formatMoney( const QString & numStr )</pre>
|-
| Money || Number || <pre>formatMoney( double num,
const QString & currency,
int digits = -1 )</pre>
|-
| Date || String || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false)</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat = true,
bool includeSecs = false )</pre>
|}

Similar functions exist to read information provided by the user at runtime in their localized format, e.g. readNumber() or readMoney().

== Calendaring ==

Developing applications dealing with dates and time, such as calendars, is a very complex area. Not only may the displayed string containing a date or time may look different based on locale, but one also has to take care of other aspects such as:
* which day in the week is the first one (cf int weekStartDay())
* how many months in a year there are
* "era"-based calendars
* whether to use 24-hour time format (cf bool use12Clock())

KLocale provides, among others, these methods:

{|
|+ Calendar Data Functions
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Date || /klocal/QDate || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false )</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat=true,
bool includeSecs=false )</pre>
|}

== Further Information ==
For additional information have a look at the [http://i18n.kde.org i18n pages].

[[Category:KDE3]]
[[Category:Architecture]]
[[Category:Developers]]

@@ Line 1: / Line 1: @@
 {{TipBox
- |text=This is a page describing how to implement localization in programs. If you want to contribute translations see the [[Translating Trinity]] page.
+ |text=This is a page describing how to implement localization in programs. If you just want to contribute TDE translations please [[TDE Weblate Translation Workspace|see this page]].
 }}

@@ Line 1: / Line 1: @@
+{{TipBox
+ |text=This is a page describing how to implement localization in programs. If you want to contribute translations see the [[Translating Trinity]] page.
+}}
 Reaching a broad audience of users and developers requires that your software can be translated and otherwise shaped at runtime to be linguistically and culturally relevant to whomever is sitting in front of the computer. This is the realm of '''localization''' and this tutorial steps you through what is needed to make your application localizable.

@@ Line 150: / Line 150: @@
 </syntaxhighlight>
-The translation macros require some tools to be installed, most notably a version of <tt>xgettext</tt> with a set of KDE 3.x-specific patches. You can get the last version [https://download.kde.org/devel/gettext-kde/ here].
+The translation macros require some tools to be installed, most notably a version of <tt>gettext</tt> with a set of KDE 3.x-specific patches. You can install the last version with APT if you are using Debian/Ubuntu/etc., or else get it [https://download.kde.org/devel/gettext-kde/ here], apply patches from the Debian packages and then compile it yourself.
 == Further Information ==

@@ Line 147: / Line 147: @@
 <syntaxhighlight lang="shell-session">
-$ cmake -P CMakeL10n.ttx
+$ cmake -P CMakeL10n.txt
 </syntaxhighlight>
-The translation macros require some tools to be installed, most notably a version of xgettext with KDE 3.x patches. You can get the last version [https://download.kde.org/devel/gettext-kde/ here].
+The translation macros require some tools to be installed, most notably a version of <tt>xgettext</tt> with a set of KDE 3.x-specific patches. You can get the last version [https://download.kde.org/devel/gettext-kde/ here].
 == Further Information ==

@@ Line 139: / Line 139: @@
                 bool includeSecs=false )</pre>
 |}
+== Generating translations ==
+Translation rules are contained in <tt>CMakeL10n.txt</tt> files in each directory in the source tree.
+You can (re)-generate translation templates (<tt>.pot</tt> files) by running:
+<syntaxhighlight lang="shell-session">
+$ cmake -P CMakeL10n.ttx
+</syntaxhighlight>
+The translation macros require some tools to be installed, most notably a version of xgettext with KDE 3.x patches. You can get the last version [https://download.kde.org/devel/gettext-kde/ here].
 == Further Information ==

← Older revision	Revision as of 15:49, 21 April 2022
(No difference)

@@ Line 1: / Line 1: @@
+Reaching a broad audience of users and developers requires that your software can be translated and otherwise shaped at runtime to be linguistically and culturally relevant to whomever is sitting in front of the computer. This is the realm of '''localization''' and this tutorial steps you through what is needed to make your application localizable.
-[[Category:KDE3]]
-[[Category:Architecture]]
-[[Category:Developers]]
-{{Applicable to TDE}}
-Reaching a broad audience of users and developers requires that your software can be translated and otherwise shaped at runtime to be linguistically and culturally relevant to whomever is sitting in front of the computer. This is the realm of localization and this tutorial steps you through what is needed to make your application localizable.
 __TOC__
@@ Line 154: / Line 148: @@
 == Further Information ==
 You might find some useful generic information at the [http://i18n.kde.org KDE's i18n pages].
+[[Category:KDE3]]
+[[Category:Architecture]]
+[[Category:Developers]]

@@ Line 6: / Line 6: @@
 Reaching a broad audience of users and developers requires that your software can be translated and otherwise shaped at runtime to be linguistically and culturally relevant to whomever is sitting in front of the computer. This is the realm of localization and this tutorial steps you through what is needed to make your application localizable.
+__TOC__
 == What is Internationalization and Localization? ==