Locale Library - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:05:04Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:05, 26 January 2025
Line 30:		Line 30:
	The following code fragment opens the current system locale, prints the English name of the associated language (as retrieved from the Locale structure), and closes the locale:		The following code fragment opens the current system locale, prints the English name of the associated language (as retrieved from the Locale structure), and closes the locale:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Locale *currentLocale;		struct Locale *currentLocale;

Line 55:		Line 55:
	The following code fragment opens the current system locale, prints the native name of the language and the localized name of the first month of the year, then closes the locale:		The following code fragment opens the current system locale, prints the native name of the language and the localized name of the first month of the year, then closes the locale:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Locale *currentLocale;		struct Locale *currentLocale;

Line 91:		Line 91:
	In program code you need to call the DOS Library function GetVar(). The following snippet shows how to retrieve the name of the current character set:		In program code you need to call the DOS Library function GetVar(). The following snippet shows how to retrieve the name of the current character set:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	char charSet[32];		char charSet[32];

Costel Mincea: /* Environment Variables */

2016-12-18T09:27:22Z

Environment Variables

← Older revision		Revision as of 09:27, 18 December 2016
Line 74:		Line 74:
	; LanguageName		; LanguageName
	: The name of the current default language as used in the system. This is the English name of the language, and it is the same value you would obtain from the ''loc_LanguageName'' field of the Locale structure as returned by OpenLocale(NULL).		: The name of the current default language as used in the system. This is the English name of the language, and it is the same value you would obtain from the ''loc_LanguageName'' field of the Locale structure as returned by OpenLocale(NULL).

			; Language
			: The name of the current default language as used in the system. This is the localized name of the language as it was used in the past, if available.

	; Charset		; Charset
Line 80:		Line 83:
	In a CLI environment (the Shell, for example) you can use the AmigaDOS [[AmigaOS_Manual:_AmigaDOS_Command_Reference#GETENV\|GETENV]] command to retrieve and display the respective variable value:		In a CLI environment (the Shell, for example) you can use the AmigaDOS [[AmigaOS_Manual:_AmigaDOS_Command_Reference#GETENV\|GETENV]] command to retrieve and display the respective variable value:

	1> GETENV ~~Language~~		1> GETENV LanguageName
	czech		czech

Daniel Jedlicka: Added examples for the Environment Variables sub-section

2015-05-02T06:31:18Z

Added examples for the Environment Variables sub-section

@@ Line 77: / Line 77: @@
 ; Charset
 : The MIME name of the current default character set as used in the system. Please note that this value does NOT correspond with that of the ''loc_CodeSet'' field of the Locale structure returned by OpenLocale(NULL). The ''Charset'' environmental variable contains the name of the character set (i.e. a string value), whereas ''loc_CodeSet'' provides its IANA number (that is, an integer value).
 == Catalogs ==

Daniel Jedlicka: Started the Catalogs section.

2015-04-11T05:45:00Z

Started the Catalogs section.

← Older revision		Revision as of 05:45, 11 April 2015
Line 77:		Line 77:
	; Charset		; Charset
	: The MIME name of the current default character set as used in the system. Please note that this value does NOT correspond with that of the ''loc_CodeSet'' field of the Locale structure returned by OpenLocale(NULL). The ''Charset'' environmental variable contains the name of the character set (i.e. a string value), whereas ''loc_CodeSet'' provides its IANA number (that is, an integer value).		: The MIME name of the current default character set as used in the system. Please note that this value does NOT correspond with that of the ''loc_CodeSet'' field of the Locale structure returned by OpenLocale(NULL). The ''Charset'' environmental variable contains the name of the character set (i.e. a string value), whereas ''loc_CodeSet'' provides its IANA number (that is, an integer value).

			== Catalogs ==

			For most applications (regardless of the operating system), the grunt of the localization work lies in translating the user interface. This typically involves the translation of all text strings that are used and displayed by the program: window titles, menu- and button labels, various program messages etc. In AmigaOS, all strings translated into a particular language are put into a special binary file called the ''catalog'' (also referred to as ''locale catalog'' or ''message catalog'').

			A separate catalog file is needed for every language that is to be supported by the application, except English. A localized Amiga application is required to provide a full set of ''built-in strings'' in English to default to. These strings are part of the application executable and will be used if no catalog files are found – or, of course, if the English language is selected for the current [[#Locale\|locale]].

			(to be continued)

	== Function Reference ==		== Function Reference ==

Daniel Jedlicka: Added the Environment Variables section.

2015-04-10T08:17:56Z

Added the Environment Variables section.

← Older revision		Revision as of 08:17, 10 April 2015
Line 22:		Line 22:
	Locale settings are made on the user level, from the Locale editor found in your Prefs drawer. For example, a Danish user would normally use the editor to select a Danish locale for his/her system.		Locale settings are made on the user level, from the Locale editor found in your Prefs drawer. For example, a Danish user would normally use the editor to select a Danish locale for his/her system.

	=== Accessing ~~locale~~ ~~parameters~~ ===		=== Accessing Locale Parameters ===

	The Locale Library provides access to the respective settings and parameters via a public data structure called, quite predictably, ''Locale'' (see the <libraries/locale.h> include file for definition; the structure is rather extensive). The programmer can query about the individual locale parameters by calling OpenLocale() and then reading from the data structure, the pointer to which is returned as the function result. You will also need this pointer if you want to use certain Locale Library functions.		The Locale Library provides access to the respective settings and parameters via a public data structure called, quite predictably, ''Locale'' (see the <libraries/locale.h> include file for definition; the structure is rather extensive). The programmer can query about the individual locale parameters by calling OpenLocale() and then reading from the data structure, the pointer to which is returned as the function result. You will also need this pointer if you want to use certain Locale Library functions.
Line 28:		Line 28:
	OpenLocale() takes the name of the locale as parameter. Most applications will pass NULL, indicating the current system locale. The provided data structure is strictly read-only, and the pointer to it can no longer be used after you call CloseLocale().		OpenLocale() takes the name of the locale as parameter. Most applications will pass NULL, indicating the current system locale. The provided data structure is strictly read-only, and the pointer to it can no longer be used after you call CloseLocale().

	The following code fragment opens the current system locale, prints the name of the associated language (as retrieved from the Locale structure), and closes the locale:		The following code fragment opens the current system locale, prints the English name of the associated language (as retrieved from the Locale structure), and closes the locale:

	<syntaxhighlight>		<syntaxhighlight>
Line 40:		Line 40:
	</syntaxhighlight>		</syntaxhighlight>

	=== Standard ~~locale~~ ~~strings~~ ===		=== Standard Locale Strings ===

	The library also provides a set of commonly-used strings, the localized versions of which are part of each locale. These "standard" strings include:		The library also provides a set of commonly-used strings, the localized versions of which are part of each locale. These "standard" strings include:
Line 49:		Line 49:
	* the "yes/no" strings used as response in requester gadgets		* the "yes/no" strings used as response in requester gadgets
	* the characters used as quotation marks in the particular language		* the characters used as quotation marks in the particular language
	* the native name of the language (~~e.g.~~ "Deutsch" for German).		* the native name of the language ("Deutsch" for German, "Français" for French, etc.).

	An AmigaOS application – for example, a calendar or a [https://en.wikipedia.org/wiki/Personal_organizer personal organiser] – will not provide these strings but, rather, obtain them from the locale using GetLocaleStr() and a respective string code as defined in <libraries/locale.h>.		An AmigaOS application – for example, a calendar or a [https://en.wikipedia.org/wiki/Personal_organizer personal organiser] – will not provide these strings but, rather, obtain them from the locale using GetLocaleStr() and a respective string code as defined in <libraries/locale.h>.
Line 68:		Line 68:
	</syntaxhighlight>		</syntaxhighlight>

			=== Environment Variables ===
	(to be continued)

			Certain common locale parameters can also be retrieved from global environment variables that the library maintains. These include:

			; LanguageName
			: The name of the current default language as used in the system. This is the English name of the language, and it is the same value you would obtain from the ''loc_LanguageName'' field of the Locale structure as returned by OpenLocale(NULL).

			; Charset
			: The MIME name of the current default character set as used in the system. Please note that this value does NOT correspond with that of the ''loc_CodeSet'' field of the Locale structure returned by OpenLocale(NULL). The ''Charset'' environmental variable contains the name of the character set (i.e. a string value), whereas ''loc_CodeSet'' provides its IANA number (that is, an integer value).

	== Function Reference ==		== Function Reference ==

Daniel Jedlicka: Added the Standard locale strings sub-section.

2015-04-08T12:53:26Z

Added the Standard locale strings sub-section.

@@ Line 28: / Line 28: @@
 OpenLocale() takes the name of the locale as parameter. Most applications will pass NULL, indicating the current system locale. The provided data structure is strictly read-only, and the pointer to it can no longer be used after you call CloseLocale().
-The following code fragment opens the current system locale, prints the name of the associated language and the localized name of the first month of the year, then closes the locale:
+The following code fragment opens the current system locale, prints the name of the associated language (as retrieved from the Locale structure), and closes the locale:
 <syntaxhighlight>
@@ Line 36: / Line 36: @@
+{
    IDOS->Printf("The language of this locale is %s.\n", currentLocale->loc_LanguageName);
    IDOS->Printf("The first month is called %s in this language.\n",
                 ILocale->GetLocaleStr(currentLocale, MON_1));

Daniel Jedlicka: Extended the Locale section.

2015-04-07T20:45:41Z

Extended the Locale section.

← Older revision		Revision as of 20:45, 7 April 2015
Line 20:		Line 20:
	In the context of AmigaOS, the term ''locale'' refers to a set of parameters defining various language-specific and country-specific properties. Localized Amiga software takes these properties from system files stored on disk, instead of hardcoding them into the application. Thus, no recompiling is required: properly localized Amiga applications dynamically adapt themselves to the current locale.		In the context of AmigaOS, the term ''locale'' refers to a set of parameters defining various language-specific and country-specific properties. Localized Amiga software takes these properties from system files stored on disk, instead of hardcoding them into the application. Thus, no recompiling is required: properly localized Amiga applications dynamically adapt themselves to the current locale.

			Locale settings are made on the user level, from the Locale editor found in your Prefs drawer. For example, a Danish user would normally use the editor to select a Danish locale for his/her system.
	On the user level, locale settings for the entire operating system are made from the Locale editor in SYS:Prefs.

			=== Accessing locale parameters ===
	The programmer can access the individual locale parameters by calling OpenLocale() and then reading from the Locale structure, the pointer to which is returned as the function result. An application would normally want to query about the current system locale, which is indicated by passing NULL as parameter to OpenLocale(). The following code fragment opens the current system locale and prints the name of the associated language:

			The Locale Library provides access to the respective settings and parameters via a public data structure called, quite predictably, ''Locale'' (see the <libraries/locale.h> include file for definition; the structure is rather extensive). The programmer can query about the individual locale parameters by calling OpenLocale() and then reading from the data structure, the pointer to which is returned as the function result. You will also need this pointer if you want to use certain Locale Library functions.

			OpenLocale() takes the name of the locale as parameter. Most applications will pass NULL, indicating the current system locale. The provided data structure is strictly read-only, and the pointer to it can no longer be used after you call CloseLocale().

			The following code fragment opens the current system locale, prints the name of the associated language and the localized name of the first month of the year, then closes the locale:

	<syntaxhighlight>		<syntaxhighlight>
Line 30:		Line 36:
	{		{
	IDOS->Printf("The language of this locale is %s.\n", currentLocale->loc_LanguageName);		IDOS->Printf("The language of this locale is %s.\n", currentLocale->loc_LanguageName);
			IDOS->Printf("The first month is called %s in this language.\n",
			ILocale->GetLocaleStr(currentLocale, MON_1));
	ILocale->CloseLocale(currentLocale);		ILocale->CloseLocale(currentLocale);
	}		}
	</syntaxhighlight>		</syntaxhighlight>

			(to be continued)

	== Function Reference ==		== Function Reference ==

Daniel Jedlicka: Reworded the introductory section.

2015-04-04T06:47:14Z

Reworded the introductory section.

← Older revision		Revision as of 06:47, 4 April 2015
Line 1:		Line 1:
	== Introduction ==		== Introduction ==

	~~In today's globalized world~~, computer software is commonly ~~sold~~ and used in ~~different~~ ~~countries.~~ ~~Each~~ country ~~represents~~ a ~~specific~~ ~~environment,~~ in ~~which~~ certain aspects, ~~features~~ or ~~behaviour~~ of ~~the~~ ~~software~~ ~~may~~ ~~not~~ ~~produce~~ a ~~desirable~~ ~~user~~ ~~experience~~. Therefore, modern computer applications need to be designed ~~and adapted~~ to ~~respect~~ various local conventions and customs. ~~Your~~ product – free or commercial – can easily get rejected by users ~~if you fail to do so~~.		Today, computer software is commonly marketed and used globally. But programs that work for users in one country or territory may not work so well in another, because local specifics can turn certain aspects into barriers hampering usability. An obvious barrier is language but there are others. For example, an accounting program would be an utter flop if it didn't support different numeric systems and currencies. Therefore, modern computer applications need to be designed to account for various local conditions, conventions and customs. Otherwise your product – free or commercial – can easily get rejected by users.

	The process of adapting software to the linguistic, cultural and technical requirements of a local market is called ''localization''. This process typically entails:		The process of adapting software to the linguistic, cultural and technical requirements of a local market is called ''localization''. This process typically entails:
Line 10:		Line 10:
	* use of local units of measurement, currency etc.		* use of local units of measurement, currency etc.
	* use of language-specific sorting rules		* use of language-specific sorting rules
	* ~~use~~ of a particular character set		* support for a particular character set
	* adaptation of keyboard shortcuts (where mnemonics are desirable to be preserved)		* adaptation of keyboard shortcuts (where mnemonics are desirable to be preserved)
	* etc.		* etc.

	Amiga software developers are encouraged to use the Locale Library to localize their applications. Additional tools are available to help in the process.		Amiga software developers are encouraged to use the Locale Library to localize their applications. Additional tools are also available to help in the process.

	== Locale ==		== Locale ==

Daniel Jedlicka: Added the Locale section.

2015-04-03T21:16:35Z

Added the Locale section.

← Older revision		Revision as of 21:16, 3 April 2015
Line 1:		Line 1:
	== Introduction ==		== Introduction ==

	In today's globalized world, computer software is commonly sold and used in different countries. Each country represents a specific environment, in which certain aspects, features or behaviour of the software may not produce a desirable user experience. Therefore, modern computer applications need to be designed and adapted to respect various local conventions. Your product – free or commercial – can easily get rejected by users if you fail to do so.		In today's globalized world, computer software is commonly sold and used in different countries. Each country represents a specific environment, in which certain aspects, features or behaviour of the software may not produce a desirable user experience. Therefore, modern computer applications need to be designed and adapted to respect various local conventions and customs. Your product – free or commercial – can easily get rejected by users if you fail to do so.

	The process of adapting software to the linguistic, cultural and technical requirements of a local market is called ''localization''. This process typically entails:		The process of adapting software to the linguistic, cultural and technical requirements of a local market is called ''localization''. This process typically entails:

	* translation of the application's user interface to the target language		* translation of the application's user interface into the target language
	* translation of the application's documentation and help files to the target language		* translation of the application's documentation and help files into the target language
	* adaptation to specific writing conventions such as punctuation, number formatting, date and time format etc.		* adaptation to specific writing conventions such as punctuation, number formatting, date and time format etc.
	* use of local units of measurement, currency etc.		* use of local units of measurement, currency etc.
	* use of language-specific sorting rules		* use of language-specific sorting rules
			* use of a particular character set
	* adaptation of keyboard shortcuts (where mnemonics is desirable to be preserved)		* adaptation of keyboard shortcuts (where mnemonics are desirable to be preserved)
	* etc.		* etc.

	In ~~AmigaOS,~~ the Locale Library is ~~the~~ ~~component~~ ~~provided~~ to ~~software~~ ~~developers~~ to help ~~them~~ ~~localize~~ ~~their applications~~.		Amiga software developers are encouraged to use the Locale Library to localize their applications. Additional tools are available to help in the process.

			== Locale ==

			In the context of AmigaOS, the term ''locale'' refers to a set of parameters defining various language-specific and country-specific properties. Localized Amiga software takes these properties from system files stored on disk, instead of hardcoding them into the application. Thus, no recompiling is required: properly localized Amiga applications dynamically adapt themselves to the current locale.

			On the user level, locale settings for the entire operating system are made from the Locale editor in SYS:Prefs.

			The programmer can access the individual locale parameters by calling OpenLocale() and then reading from the Locale structure, the pointer to which is returned as the function result. An application would normally want to query about the current system locale, which is indicated by passing NULL as parameter to OpenLocale(). The following code fragment opens the current system locale and prints the name of the associated language:

			<syntaxhighlight>
			struct Locale *currentLocale;

			if ( (currentLocale = ILocale->OpenLocale(NULL)) )
			{
			IDOS->Printf("The language of this locale is %s.\n", currentLocale->loc_LanguageName);
			ILocale->CloseLocale(currentLocale);
			}
			</syntaxhighlight>

	== Function Reference ==		== Function Reference ==

Daniel Jedlicka: Added text for Introduction.

2015-04-03T14:00:15Z

Added text for Introduction.

← Older revision		Revision as of 14:00, 3 April 2015
Line 1:		Line 1:
	== Introduction ==		== Introduction ==

			In today's globalized world, computer software is commonly sold and used in different countries. Each country represents a specific environment, in which certain aspects, features or behaviour of the software may not produce a desirable user experience. Therefore, modern computer applications need to be designed and adapted to respect various local conventions. Your product – free or commercial – can easily get rejected by users if you fail to do so.

			The process of adapting software to the linguistic, cultural and technical requirements of a local market is called ''localization''. This process typically entails:

			* translation of the application's user interface to the target language
			* translation of the application's documentation and help files to the target language
			* adaptation to specific writing conventions such as punctuation, number formatting, date and time format etc.
			* use of local units of measurement, currency etc.
			* use of language-specific sorting rules
			* adaptation of keyboard shortcuts (where mnemonics is desirable to be preserved)
			* etc.

			In AmigaOS, the Locale Library is the component provided to software developers to help them localize their applications.

	== Function Reference ==		== Function Reference ==