Translations / i18n / localizations for programs/ko: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## 개요
2	2
3	3		This is about how a program can use different strings for various languages like english, chinese, german, finnish, italian, ... . Basically it works like this: Add a resourcestring for every caption, compile to get the .rst and/or .po files (the IDE can do this automatically), create one translated .po file for each language (there are free graphical tools) and use the functions of the LCL translations unit to load the right one at start of the program.
4	4
5	5		## 날자, 시간 그리고 숫자형태
6	6
7	7		Under Linux, BSD, Mac OS X there are several locales defining things like time and date format or the thousand separator. In order to initialize the RTL you need to iclude the clocale unit in the uses section of your program (lpr file).
8	8
9	9		## Resourcestrings
10	10
11	11		For example
12	12
13	13		``` pascal
14	14		resourcestring
15	15		Caption1 = 'Some text';
16	16		HelloWorld1 = 'Hello World';
17	17		```
18	18
19	19		These are like normal string constants, that means you can assign them to any string. For example
20	20
21	21		``` pascal
22	22		Label1.Caption := HelloWorld1;
23	23		```
24	24
25	25		When fpc compiles them, it creates for each unit a file unitname.rst, containing the resourcestring data (name + content).
26	26
27	27		## .po Files
28	28
29	29		There are many free graphical tools to edit .po files, which are simple text like the .rst files, but with some more options, like a header providing fields for author, encoding, language and date. Every FPC installation provides the tool rstconv (windows: rstconv.exe). This tool can be used to convert a .rst file into a .po file. The IDE can do this automatically. Some free tools: kbabel, poedit, virtaal.
30	30
31	31		Virtaal has a translation memory containing source-target language pairs for items that you already translated once, and a translation suggestion function that shows already translated terms in various open source software packages. These function may save you a lot of work and improve consistency.
32	32
33	33		Example of using rstconv directly:
34	34
35		-	~~`rstconv -i unit1.rst -o unit1.po`~~
	35	+	```text
	36	+	rstconv -i unit1.rst -o unit1.po
	37	+	```
36	38
37	39		## 번역
38	40
39	41		For every language the .po file must be copied and translated. The LCL translation unit uses the common language codes (en=english, de=german, it=italian, ...) to search. For example the German translation of unit1.po would be unit1.de.po. To achieve this, copy the unit1.po file to unit1.de.po, unit1.it.po, and whatever language you want to support and then the translators can edit their specific .po file.
40	42
41	43		> Note: For Brazilians/Portuguese: Lazarus IDE and LCL only have a Brazilian Portuguese translation and these files have 'pt_BR.po' extensions
42	44
43	45		## IDE options for automatic updates of .po files
44	46
45	47		- The unit containing the resource strings must be added to the package or project.
46	48		- You must provide a .po path, this means a separate directory. For example: create a sub directory language in the package / project directory. For projects go to the Project \> Project Options. For packages go to Options \> IDE integration.
47	49
48	50		When this options are enabled, the IDE generates or updates the base .po file using the information contained in .rst and .lrt files (rstconv tool is then not necesary). The update process begins by collecting all existing entries found in base .po file and in .rst and .lrt files and then applying the following features it finds and brings up to date any translated .xx.po file.
49	51
50	52		### Removal of Obsolete entries
51	53
52	54		Entries in the base .po file that are not found in .rst and .lrt files are removed. Subsequently, all entries found in translated .xx.po files not found in the base .po file are also removed. This way, .po files are not cluttered with obsolete entries and translators don't have to translate entries that are not used.
53	55
54	56		### Duplicate entries
55	57
56	58		Duplicate entries occur when for some reason the same text is used for diferent resource strings, a random example of this is the file lazarus/ide/lazarusidestrconst.pas for the 'Gutter' string:
57	59
58	60		``` pascal
59	61		dlfMouseSimpleGutterSect = 'Gutter';
60	62		dlgMouseOptNodeGutter = 'Gutter';
61	63		dlgGutter = 'Gutter';
62	64		dlgAddHiAttrGroupGutter = 'Gutter';
63	65		```
64	66
65	67		A converted .rst file for this resource strings would look similar to this in a .po file:
66	68
67		-	~~`#: lazarusidestrconsts.dlfmousesimpleguttersect`\~~
68		-	~~`msgid "Gutter"`\~~
69		-	~~`msgstr ""`\~~
70		-	~~`#: lazarusidestrconsts.dlgaddhiattrgroupgutter`\~~
71		-	~~`msgid "Gutter"`\~~
72		-	~~`msgstr ""`\~~
73		-	~~`etc.`\~~
	69	+	```text
	70	+	#: lazarusidestrconsts.dlfmousesimpleguttersect
	71	+	msgid "Gutter"
	72	+	msgstr ""
	73	+	#: lazarusidestrconsts.dlgaddhiattrgroupgutter
	74	+	msgid "Gutter"
	75	+	msgstr ""
	76	+	etc.
	77	+	```
74	78
75	79		Where the lines starting with "#: " are considered comments and the tools used to translate this entries see the repeated msgid "Gutter" lines like duplicated entries and produce errors or warnings on loading or saving. Duplicate entries are considered a normal eventuality on .po files and they need to have some context attached to them. The msgctxt keyword is used to add context to duplicated entries and the automatic update tool use the entry ID (the text next to "#: " prefix) as the context, for the previous example it would produce something like this:
76	80
77		-	~~`#: lazarusidestrconsts.dlfmousesimpleguttersect`\~~
78		-	~~`msgctxt "lazarusidestrconsts.dlfmousesimpleguttersect"`\~~
79		-	~~`msgid "Gutter"`\~~
80		-	~~`msgstr ""`\~~
81		-	~~`#: lazarusidestrconsts.dlgaddhiattrgroupgutter`\~~
82		-	~~`msgctxt "lazarusidestrconsts.dlgaddhiattrgroupgutter"`\~~
83		-	~~`msgid "Gutter"`\~~
84		-	~~`msgstr ""`\~~
85		-	~~`etc.`\~~
	81	+	```text
	82	+	#: lazarusidestrconsts.dlfmousesimpleguttersect
	83	+	msgctxt "lazarusidestrconsts.dlfmousesimpleguttersect"
	84	+	msgid "Gutter"
	85	+	msgstr ""
	86	+	#: lazarusidestrconsts.dlgaddhiattrgroupgutter
	87	+	msgctxt "lazarusidestrconsts.dlgaddhiattrgroupgutter"
	88	+	msgid "Gutter"
	89	+	msgstr ""
	90	+	etc.
	91	+	```
86	92
87	93		On translated .xx.po files the automatic tool does one additional check: if the duplicated entry was already translated, the new entry gets the old translation, so it appears like being translated automatically.
88	94
89	95		The automatic detection of duplicates is not yet perfect, duplicate detection is made as items are added to the list and it may happen that some untranslated entries are read first. So it may take several passes to get all duplicates automatically translated by the tool.
90	96
91	97		### Fuzzy entries
92	98
93	99		Changes in resource strings affect translations, for example if initially a resource string was defined like:
94	100
95	101		``` pascal
96	102		dlgEdColor = 'Syntax highlight';
97	103		```
98	104
99	105		this would produce a .po entry similar to this
100	106
101		-	~~`#: lazarusidestrconsts.dlgedcolor`\~~
102		-	~~`msgid "Syntax highlight"`\~~
103		-	~~`msgstr ""`~~
	107	+	```text
	108	+	#: lazarusidestrconsts.dlgedcolor
	109	+	msgid "Syntax highlight"
	110	+	msgstr ""
	111	+	```
104	112
105	113		which if translated to Spanish (this sample was taken from lazarus history), may result in
106	114
107		-	~~`#: lazarusidestrconsts.dlgedcolor`\~~
108		-	~~`msgid "Syntax highlight"`\~~
109		-	~~`msgstr "Color"`~~
	115	+	```text
	116	+	#: lazarusidestrconsts.dlgedcolor
	117	+	msgid "Syntax highlight"
	118	+	msgstr "Color"
	119	+	```
110	120
111	121		Suppose then that at a later time, the resource string has been changed to
112	122
113	123		``` pascal
114	124		dlgEdColor = 'Colors';
115	125		```
116	126
117	127		the resulting .po entry may become
118	128
119		-	~~`#: lazarusidestrconsts.dlgedcolor`\~~
120		-	~~`msgid "Colors"`\~~
121		-	~~`msgstr ""`~~
	129	+	```text
	130	+	#: lazarusidestrconsts.dlgedcolor
	131	+	msgid "Colors"
	132	+	msgstr ""
	133	+	```
122	134
123	135		Note that while the ID remained the same lazarusidestrconsts.dlgedcolor the string has changed from 'Syntax highlight' to 'Colors'. As the string was already translated the old translation may not match the new meaning. Indeed, for the new string probably 'Colores' may be a better translation. The automatic update tool notices this situation and produces an entry like this:
124	136
125		-	~~`#: lazarusidestrconsts.dlgedcolor`\~~
126		-	~~`#, fuzzy`\~~
127		-	~~`#\| msgid "Syntax highlight"`\~~
128		-	~~`msgctxt "lazarusidestrconsts.dlgedcolor"`\~~
129		-	~~`msgid "Colors"`\~~
130		-	~~`msgstr "Color"`~~
	137	+	```text
	138	+	#: lazarusidestrconsts.dlgedcolor
	139	+	#, fuzzy
	140	+	#\| msgid "Syntax highlight"
	141	+	msgctxt "lazarusidestrconsts.dlgedcolor"
	142	+	msgid "Colors"
	143	+	msgstr "Color"
	144	+	```
131	145
132	146		In terms of .po file format, the "#," prefix means the entry has a flag (fuzzy) and translator programs may present a special GUI to the translator user for this item. In this case, the flag would mean that the translation in its current state is doubtful and needs to be reviewed more carefully by translator. The "#\\|" prefix indicates what was the previous untranslated string of this entry and gives the translator a hint why the entry was marked as fuzzy.
133	147
134	148		## Translating Forms, Datamodules and Frames
135	149
136	150		When the i18n option is enabled for the project / package then the IDE automatically creates .lrt files for every form. It creates the .lrt file on saving a unit. So, if you enable the option for the first time, you must open every form once, move it a little bit, so that it is modified, and save the form. For example if you save a form unit1.pas the IDE creates a unit1.lrt. And on compile the IDE gathers all strings of all .lrt files and all .rst file into a single .po file (projectname.po or packagename.po) in the i18n directory.
137	151
138	152		For the forms to be actually translated at runtime, you have to assign a translator to LRSTranslator (defined in LResources) in the initialization section to one of your units
139	153
140	154		``` pascal
141	155		...
142	156		uses
143	157		...
144	158		LResources;
145	159		...
146	160		...
147	161		initialization
148	162		LRSTranslator := TPoTranslator.Create('/path/to/the/po/file');
149	163		```
150	164
151	165		However there's no TPoTranslator class (i.e a class that translates using .po files) available in the LCL. This is a possible implementation (partly lifted from DefaultTranslator.pas in the LCL): The following code isn't needed anymore if you use recent Lazarus 0.9.29 snapshots. Simply include DefaultTranslator in Uses clause.
152	166
153	167		``` pascal
154	168		unit PoTranslator;
155	169
156	170		{$mode objfpc}{$H+}
157	171
158	172		interface
159	173
160	174		uses
161	175		Classes, SysUtils, LResources, typinfo, Translations;
162	176
163	177		type
164	178
165	179		{ TPoTranslator }
166	180
167	181		TPoTranslator=class(TAbstractTranslator)
168	182		private
169	183		FPOFile:TPOFile;
170	184		public
171	185		constructor Create(POFileName:string);
172	186		destructor Destroy;override;
173	187		procedure TranslateStringProperty(Sender:TObject;
174	188		const Instance: TPersistent; PropInfo: PPropInfo; var Content:string);override;
175	189		end;
176	190
177	191		implementation
178	192
179	193		{ TPoTranslator }
180	194
181	195		constructor TPoTranslator.Create(POFileName: string);
182	196		begin
183	197		inherited Create;
184	198		FPOFile:=TPOFile.Create(POFileName);
185	199		end;
186	200
187	201		destructor TPoTranslator.Destroy;
188	202		begin
189	203		FPOFile.Free;
190	204		inherited Destroy;
191	205		end;
192	206
193	207		procedure TPoTranslator.TranslateStringProperty(Sender: TObject;
194	208		const Instance: TPersistent; PropInfo: PPropInfo; var Content: string);
195	209		var
196	210		s: String;
197	211		begin
198	212		if not Assigned(FPOFile) then exit;
199	213		if not Assigned(PropInfo) then exit;
200	214		{DO we really need this?}
201	215		if Instance is TComponent then
202	216		if csDesigning in (Instance as TComponent).ComponentState then exit;
203	217		{End DO :)}
204	218		if (AnsiUpperCase(PropInfo^.PropType^.Name)<>'TTRANSLATESTRING') then exit;
205	219		s:=FPOFile.Translate(Content, Content);
206	220		if s<>'' then Content:=s;
207	221		end;
208	222
209	223		end.
210	224		```
211	225
212	226		Alternatively you can transform the .po file into .mo using msgfmt (isn't needed anymore if you use recent 0.9.29 snapshot) and simply use the DefaultTranslator unit
213	227
214	228		``` pascal
215	229		...
216	230		uses
217	231		...
218	232		DefaultTranslator;
219	233		```
220	234
221	235		which will automatically look in several standard places for a .po file (higher precedence) or .mo file (the disadvantage is that you'll have to keep around both the .mo files for the DefaultTranslator unit and the .po files for TranslateUnitResourceStrings). If you use DefaultTranslator, it will try to automatically detect the language based on the LANG environment variable (overridable using the --lang command line switch), then look in these places for the translation (LANG stands for the desired language, ext can be either po or mo):
222	236
223	237		- \<Application Directory\>/\<LANG\>/\<Application Filename\>.\<ext\>
224	238		- \<Application Directory\>/languages/\<LANG\>/\<Application Filename\>.\<ext\>
225	239		- \<Application Directory\>/locale/\<LANG\>/\<Application Filename\>.\<ext\>
226	240		- \<Application Directory\>/locale/LC_MESSAGES/\<LANG/\>\<Application Filename\>.\<ext\>
227	241
228	242		under unix-like systems it will also look in
229	243
230	244		- /usr/share/locale/\<LANG\>/LC_MESSAGES/\<Application Filename\>.\<ext\>
231	245
232	246		as well as using the short part of the language (e.g. if it is "es_ES" or "es_ES.UTF-8" and it doesn't exist it will also try "es")
233	247
234	248		## Translating at start of program
235	249
236	250		For every .po file, you must call TranslateUnitResourceStrings. The LCL po file is lclstrconsts. For example you do this in FormCreate of your MainForm:
237	251
238	252		``` pascal
239	253		uses
240	254		..., gettext, translations;
241	255
242	256		procedure TForm1.FormCreate(Sender: TObject);
243	257		var
244	258		PODirectory, Lang, FallbackLang: String;
245	259		begin
246	260		PODirectory := '/path/to/lazarus/lcl/languages/';
247	261		GetLanguageIDs(Lang, FallbackLang);
248	262		Translations.TranslateUnitResourceStrings('LCLStrConsts', PODirectory + 'lclstrconsts.%s.po', Lang, FallbackLang);
249	263
250	264		// the following dialog now shows translated buttons:
251	265		MessageDlg('Title', 'Text', mtInformation, [mbOk, mbCancel, mbYes], 0);
252	266		end;
253	267		```
254	268
255	269		## Compiling po files into the executable
256	270
257	271		If you don't want to install the .po files, but put all files of the application into the executable, use the following:
258	272
259	273		- Create a new unit (not a form!).
260	274		- Convert the .po file(s) to .lrs using tools/lazres:
261	275
262	276		./lazres unit1.lrs unit1.de.po
263	277
264	278		This will create an include file unit1.lrs beginning with
265	279
266	280		``` pascal
267	281		LazarusResources.Add('unit1.de','PO',[
268	282		...
269	283		```
270	284
271	285		- Add the code:
272	286
273	287		``` pascal
274	288		uses LResources, Translations;
275	289
276	290		resourcestring
277	291		MyCaption = 'Caption';
278	292
279	293		function TranslateUnitResourceStrings: boolean;
280	294		var
281	295		r: TLResource;
282	296		POFile: TPOFile;
283	297		begin
284	298		r:=LazarusResources.Find('unit1.de','PO');
285	299		POFile:=TPOFile.Create;
286	300		try
287	301		POFile.ReadPOText(r.Value);
288	302		Result:=Translations.TranslateUnitResourceStrings('unit1',POFile);
289	303		finally
290	304		POFile.Free;
291	305		end;
292	306		end;
293	307
294	308		initialization
295	309		{$I unit1.lrs}
296	310		```
297	311
298	312		- Call TranslateUnitResourceStrings at the beginning of the program. You can do that in the initialization section if you like.
299	313
300	314		## Cross-platform method to determine system language
301	315
302	316		The following function delivers a string that represents the language of the user interface. It supports Linux, Mac OS X and Windows.
303	317
304	318		``` pascal
305	319		uses
306	320		Classes, SysUtils {add additional units that may be needed by your code here}
307	321		{$IFDEF win32}
308	322		, Windows
309	323		{$ELSE}
310	324		, Unix
311	325		{$IFDEF LCLCarbon}
312	326		, MacOSAll
313	327		{$ENDIF}
314	328		{$ENDIF}
315	329		;
316	330		```
317	331
318	332		``` pascal
319	333		function GetOSLanguage: string;
320	334		{platform-independent method to read the language of the user interface}
321	335		var
322	336		l, fbl: string;
323	337		{$IFDEF LCLCarbon}
324	338		theLocaleRef: CFLocaleRef;
325	339		locale: CFStringRef;
326	340		buffer: StringPtr;
327	341		bufferSize: CFIndex;
328	342		encoding: CFStringEncoding;
329	343		success: boolean;
330	344		{$ENDIF}
331	345		begin
332	346		{$IFDEF LCLCarbon}
333	347		theLocaleRef := CFLocaleCopyCurrent;
334	348		locale := CFLocaleGetIdentifier(theLocaleRef);
335	349		encoding := 0;
336	350		bufferSize := 256;
337	351		buffer := new(StringPtr);
338	352		success := CFStringGetPascalString(locale, buffer, bufferSize, encoding);
339	353		if success then
340	354		l := string(buffer^)
341	355		else
342	356		l := '';
343	357		fbl := Copy(l, 1, 2);
344	358		dispose(buffer);
345	359		{$ELSE}
346	360		{$IFDEF LINUX}
347	361		fbl := Copy(GetEnvironmentVariable('LC_CTYPE'), 1, 2);
348	362		{$ELSE}
349	363		GetLanguageIDs(l, fbl);
350	364		{$ENDIF}
351	365		{$ENDIF}
352	366		Result := fbl;
353	367		end;
354	368		```
355	369
356	370		## Translating the IDE
357	371
358	372		### Files
359	373
360	374		The .po files of the IDE are in the lazarus source directory:
361	375
362	376		- lazarus/languages strings for the IDE
363	377		- lcl/languages/ strings for the LCL
364	378		- ideintf/languages/ strings for the IDE interface
365	379
366	380		### Translators
367	381
368	382		- german translation is maintained by Joerg Braun.
369	383		- finnish translation is maintained by Seppo Suurtarla
370	384		- russian translation is maintained by Maxim Ganetsky
371	385
372	386		When you want to start a new translation, ask on the mailing if someone is already working on that.
373	387
374	388		Please read carefully: [[Lazarus Documentation\|Translations]]
375	389
376	390		## See also
377	391
378	392		- [[IDE Development\|IDE Development: Translations, i18n, lrt, po files]]
379	393		- [[Getting translation strings right]]
380	394		- [[Lazarus Documentation\|Translations]]
381	395
382	396		---
383	397		From the Free Pascal wiki, page "Translations / i18n / localizations for programs/ko", as it stood on 2020-03-01 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history