3 <META NAME="COPYRIGHT" CONTENT="Copyright 2001-2003, All Rights Reserved">
4 <META NAME="DOCNUMBER" CONTENT="CUPS-TRANS-1.1">
5 <META NAME="Author" CONTENT="Easy Software Products">
6 <TITLE>CUPS Translation Guide</TITLE>
12 <H2>Identification</H2>
14 <P>This translation guide provides instructions for creating
15 translations of the CUPS message catalogs and web pages for the
16 Common UNIX Printing System ("CUPS") Version 1.1 software.
18 <EMBED SRC="system-overview.shtml">
20 <H2>Document Overview</H2>
22 <P>This translation guide is organized into the following
27 <LI>2 - References</LI>
28 <LI>3 - Character Sets</LI>
29 <LI>4 - Message Catalogs</LI>
30 <LI>5 - Web Interfaces</LI>
34 <EMBED SRC="references.shtml">
37 <H1>Character Sets</H1>
39 <P>CUPS uses character set files to define the mapping of local
40 character sets to Unicode code points, as well as the fonts that
41 should be used for different ranges of characters.
43 <P>CUPS includes files for common 8-bit encodings as well as
44 UTF-8 for Unicode text. The format of these files is described
45 in the CUPS Interface Design Description (IDD) document.
46 Current character sets are enumerated in the CUPS API, so in
47 order to add a new character set you must patch the CUPS source
48 as well as provide a new charset file.
50 <P>CUPS 1.1 supports the following character sets:
84 <H1>Message Catalogs</H1>
86 <P>CUPS message catalogs are text files that identify the
87 default character set for the locale and a list of localized
88 message strings for the CUPS software. The format of the
89 message catalog files is described in the CUPS IDD.
91 <P>Message catalogs are named <VAR>cups_ll</VAR>,
92 <VAR>cups_ll_CC</VAR>, or <VAR>cups_ll_CC.charset</VAR>, where
93 "ll" is the standard 2-letter abbreviation for the language,
94 "CC" is the standard 2-letter abbreviation for the country, and
95 "charset" is the charset name which may differ from the list
98 <P>Each message catalog file is stored in a subdirectory named
99 <VAR>ll</VAR>, <VAR>ll_CC</VAR>, or <VAR>ll_CC.charset</VAR> to
100 match the trailing portion of the message catalog filename.
102 <P>When translating a new message catalog, copy the <VAR>cups_C</VAR>
103 message catalog file to a new subdirectory; to translate the
104 message catalog to Canadian French, you would type the following
108 <KBD>cd locale <I>ENTER</I></KBD>
109 <KBD>mkdir fr_CA <I>ENTER</I></KBD>
110 <KBD>cp C/cups_C fr_CA/cups_fr_CA <I>ENTER</I></KBD>
113 <P>Alternatively, you could copy the existing <VAR>cups_fr</VAR>
114 message catalog and then make any changes necessary.
116 <P>Once you have make your copy of the file, edit it using your
117 favorite text editor to translate the text to the desired
118 language. Be sure to preserve any numbers starting in the first
119 column, as they indicate a new message number - you'll see this
120 for the HTTP status messages.
122 <P>Finally, add your locale to the list of locales in the
123 makefile and run the following command to install it:
126 <KBD>make install <I>ENTER</I></KBD>
129 <H1>Web Interfaces</H1>
131 <P>The CUPS scheduler provides a web interface that can be used
132 to do many common printing and administration tasks. The built-in
133 web server supports localization of web pages through the use of
134 subdirectories for each locale, e.g. "fr" for French, "de" for
135 German, "fr_ca" for French in Canada, and so forth.
137 <H2>Template Files</H2>
139 <P>Template files are HTML files with special formatting
140 characters in them that allow substition of variables and
141 arrays. The CUPS CGI programs (<CODE>admin.cgi</CODE>,
142 <CODE>classes.cgi</CODE>, <CODE>jobs.cgi</CODE>, and
143 <CODE>printers.cgi</CODE>) use these template file to provide
144 dynamic content for the web interface. Template files are
145 installed in the <VAR>/usr/share/cups/templates</VAR> directory
148 <P>Translated versions of the template files should be installed
149 in the appropriate subdirectories under
150 <VAR>/usr/share/cups/templates</VAR>. For example, Canadian
151 French template files should be stored in the
152 <VAR>/usr/share/cups/templates/fr_CA</VAR> directory.
154 <H3>Inserting Attributes and Values</H3>
156 <P>Template files consist of HTML with variable substitutions
157 for named inside curley braces "{name}". Variable names are
158 generally the IPP attribute names with the hyphen ("-") replaced
159 by the underscore ("_") character. For example, the
160 <TT>job-printer-uri</TT> attribute is renamed to
161 <TT>job_printer_uri</TT>.
163 <P>Curley braces ("{" and "}") to indicate substitutions, and
164 the backslash ("\") character for quoting. To insert any of
165 these special characters as-is you need to use the HTML
166 <CODE>&name;</CODE> mechanism or prefix each special
167 character with the backslash ("\".)</P>
169 <P>You substitute the value of a variable using
170 <CODE>{NAME}</CODE> in your template file. If the variable is
171 undefined then the <CODE>{NAME}</CODE> string is output
174 <P>To substitute an empty string if the variable is undefined, use
175 <CODE>{?NAME}</CODE> instead.</P>
177 <H3>Array Substitutions</H3>
179 <P>The number of array elements can be inserted using
180 <CODE>{#NAME}</CODE>. If the array is undefined then 0 is
181 output. The current array element (starting at 1) is inserted
182 with <CODE>{#}</CODE>.</P>
184 <P>Arrays are handled using <CODE>{[NAME]</CODE> at the beginning of a
185 section and <CODE>}</CODE> at the end. The information between the closing
186 bracket ("]") and closing brace ("}") is repeated for as many elements as
187 are in the named array. For example, the following template will display
188 a list of each job in the <CODE>job_id</CODE> array:</P>
193 <TH>Job ID</TH>
194 <TH>Destination</TH>
195 <TH>Title</TH>
200 <TD>{?job_id}</TD>
201 <TD>{?job_printer_name}</TD>
202 <TD>{?job_name}</TD>
208 <P>Arrays can be nested, however all elements within the curley
209 braces ("{" and "}") are indexed using the innermost array.</P>
211 <H3>Conditional Tests</H3>
213 <P>Templates can also test variables against specific values and
214 conditionally include text in the template. The format is:
217 {<I>variable</I>?<I>true</I>:<I>false</I>}
218 {<I>variable</I>=<I>value</I>?<I>true</I>:<I>false</I>}
219 {<I>variable</I>!<I>value</I>?<I>true</I>:<I>false</I>}
220 {<I>variable</I><<I>value</I>?<I>true</I>:<I>false</I>}
221 {<I>variable</I>><I>value</I>?<I>true</I>:<I>false</I>}
224 <P>where <VAR>true</VAR> is the text that is included if the
225 condition is true and <VAR>false</VAR> is the text that is
226 included if the condition is false. A value of <CODE>#</CODE> is
227 replaced with the current element number (starting at 1.)
229 <P>The character after the variable name specifies the condition
232 <CENTER><TABLE BORDER="1">
234 <TH WIDTH="5%">Char</TH>
235 <TH WIDTH="50%">Condition</TH>
239 <TD>True if <VAR>variable</VAR> exists.</TD>
243 <TD>True if <VAR>variable</VAR> is equal to <VAR>value</VAR>.</TD>
247 <TD>True if <VAR>variable</VAR> is not equal to <VAR>value</VAR>.</TD>
251 <TD>True if <VAR>variable</VAR> is less than <VAR>value</VAR>.</TD>
255 <TD>True if <VAR>variable</VAR> is greater than <VAR>value</VAR>.</TD>
259 <H3>Template File List</H3>
261 <P>The following template files are used by the web interface:
267 <DD>This is the initial form that is shown to add a new
272 <DD>This is the initial form that is shown to add a new
277 <DD>This is the template that is used to display an error
278 message when the admin interface sees an undefined
283 <DD>This is the template that shows the initial menu of
284 operations (add a class, manage classes, etc.)
286 <DT>choose-device.tmpl
288 <DD>This is the form that shows the list of available
293 <DD>This is the form that shows the list of available
296 <DT>choose-members.tmpl
298 <DD>This is the form that shows the list of available
299 printers that can be added to a class.
301 <DT>choose-model.tmpl
303 <DD>This is the form that shows the list of available
304 printer models/drivers.
306 <DT>choose-serial.tmpl
308 <DD>This is the form that allows the user to choose
309 a serial port and any options.
313 <DD>This is the form that allows the user to enter
314 a device URI for network printers.
318 <DD>This template shows the "class added" message.
320 <DT>class-confirm.tmpl
322 <DD>This is the template used to confirm the
325 <DT>class-deleted.tmpl
327 <DD>This template shows the "class deleted" message.
331 <DD>This template shows one or more printer classes.
333 <DT>class-modified.tmpl
335 <DD>This template shows the "class modified" message.
337 <DT>config-printer.tmpl
339 <DD>This template starts the printer configuration form.
341 <DT>config-printer2.tmpl
343 <DD>This template ends the printer configuration form.
347 <DD>This template displays a generic error message.
351 <DD>This template is used as the standard header on all dynamic
356 <DD>This template shows "job cancelled".
360 <DD>This template shows "job held".
364 <DD>This is the template that is used to display an
365 error message when the job interface sees an undefined
370 <DD>This template shows "job released".
374 <DD>This template shows "job restarted".
378 <DD>This template is used to list the print jobs on a server,
381 <DT>modify-class.tmpl
383 <DD>This template is used as the first form when modifying a
386 <DT>modify-printer.tmpl
388 <DD>This template is used as the first form when modifying a
391 <DT>option-boolean.tmpl
393 <DD>This template is used to select a boolean PPD option.
395 <DT>option-header.tmpl
397 <DD>This template is used to start a PPD option group.
399 <DT>option-pickmany.tmpl
401 <DD>This template is used to select a multi-valued PPD option.
403 <DT>option-pickone.tmpl
405 <DD>This template is used to select a single-valued PPD option.
407 <DT>option-trailer.tmpl
409 <DD>This template is used to end a PPD option group.
411 <DT>printer-accept.tmpl
413 <DD>This template shows "printer now accepting jobs".
415 <DT>printer-added.tmpl
417 <DD>This template shows "printer added".
419 <DT>printer-configured.tmpl
421 <DD>This template shows "printer configured".
423 <DT>printer-confirm.tmpl
425 <DD>This template asks the user to confirm the deletion of a printer.
427 <DT>printer-deleted.tmpl
429 <DD>This template shows "printer deleted".
431 <DT>printer-modified.tmpl
433 <DD>This template shows "printer modified".
435 <DT>printer-purge.tmpl
437 <DD>This template shows "printer has been purged of all jobs".
439 <DT>printer-reject.tmpl
441 <DD>This template shows "printer now rejecting jobs".
443 <DT>printer-start.tmpl
445 <DD>This template shows "printer started".
449 <DD>This template is used to list information on one or more
452 <DT>printer-stop.tmpl
454 <DD>This template shows "printer stopped".
458 <DD>This template shows "test page printed".
462 <DD>This template is used as the standard trailer on all dynamic
467 <H2>CGI Programs</H2>
469 <P>CUPS uses four CGI programs to manage the dynamic web interfaces:
473 <LI><CODE>admin.cgi</CODE></LI>
474 <LI><CODE>classes.cgi</CODE></LI>
475 <LI><CODE>jobs.cgi</CODE></LI>
476 <LI><CODE>printers.cgi</CODE></LI>
482 <P>The <CODE>admin.cgi</CODE> program handles all of the printer
483 and class administration functions and is run for all direct
484 accesses to the <VAR>/admin</VAR> resource. For most operations it uses the
485 <CODE>PRINTER_NAME</CODE> and <CODE>OP</CODE> form variables to
486 specify the action requested.
488 <P>The following <CODE>OP</CODE> values are supported:
494 <DD>Accepts jobs on the named destination.</DD>
498 <DD>Adds a new printer class. This operation also adds
499 several other form variables:
505 <DD>Sets the members of the class. Multiple
506 <CODE>MEMBER_URIS</CODE> values can be
509 <DT>PRINTER_INFO</DT>
511 <DD>Sets the printer-info attribute for the
512 printer class, which is usually the printer
515 <DT>PRINTER_LOCATION</DT>
517 <DD>Sets the printer-location attribute for the
526 <DD>Adds a new printer. This operation also adds several other
533 <DD>Sets the baud rate for serial devices.</DD>
537 <DD>Sets the number of data bits for serial devices.</DD>
541 <DD>Sets the device URI for the printer.</DD>
545 <DD>Sets the flow control for serial devices.</DD>
549 <DD>Sets the parity checking for serial devices.</DD>
553 <DD>Sets the driver name for the printer ("raw" for a
556 <DT>PRINTER_INFO</DT>
558 <DD>Sets the printer-info attribute for the
559 printer, which is usually the printer
562 <DT>PRINTER_LOCATION</DT>
564 <DD>Sets the printer-location attribute for the
571 <DT>config-printer</DT>
573 <DD>Configures an existing printer. This operation uses
574 form variables of the same name as the options in the
575 printer's PPD file.</DD>
577 <DT>delete-class</DT>
579 <DD>Deletes a printer class. The form variable <CODE>CONFIRM</CODE>
580 may be set to any value to bypass the confirmation page.</DD>
582 <DT>delete-printer</DT>
584 <DD>Deletes a printer. The form variable <CODE>CONFIRM</CODE>
585 may be set to any value to bypass the confirmation page.</DD>
587 <DT>modify-class</DT>
589 <DD>Modifies a printer class. See the add-class operation for a
590 list of form variables.</DD>
592 <DT>modify-printer</DT>
594 <DD>Modifies a printer. See the add-printer operation for a
595 list of form variables.</DD>
599 <DD>Purges all jobs on the named destination.</DD>
603 <DD>Rejects new jobs on the named destination.</DD>
605 <DT>start-printer</DT>
607 <DD>Starts the named destination.</DD>
609 <DT>stop-printer</DT>
611 <DD>Stops the named destination.</DD>
618 <P>The <CODE>classes.cgi</CODE> program is responsible for
619 listing class information, including jobs destined for that
620 class. It is for all direct accesses to the <VAR>/classes</VAR> resource
621 and supports the optional form variables <CODE>OP</CODE> and
622 <CODE>WHICH_JOBS</CODE>. If no form variables are supplied then
623 the CGI lists all or a specific class and the active jobs on
626 <P>The following <CODE>WHICH_JOBS</CODE> values are supported:
632 <DD>Show only the completed jobs.</DD>
634 <DT>not-completed</DT>
636 <DD>Show only the active jobs.</DD>
640 <P>The following <CODE>OP</CODE> values are supported:
644 <DT>print-test-page</DT>
646 <DD>Print a PostScript test page.</DD>
652 <P>The <CODE>jobs.cgi</CODE> program handles all of the job
653 functions and is run for all direct accesses to the <VAR>/jobs</VAR>
654 resource. For most operations it uses the
655 <CODE>JOB_ID</CODE>, <CODE>OP</CODE>, and
656 <CODE>WHICH_JOBS</CODE> form variables to specify the action
659 <P>The following <CODE>WHICH_JOBS</CODE> values are supported:
665 <DD>Show only the completed jobs.</DD>
667 <DT>not-completed</DT>
669 <DD>Show only the active jobs.</DD>
673 <P>The following <CODE>OP</CODE> values are supported:
679 <DD>Cancels a job.</DD>
683 <DD>Holds a job indefinitely.</DD>
687 <DD>Releases a job for printing.</DD>
691 <DD>Restarts a stopped, cancelled, completed, or aborted
696 <H3>printers.cgi</H3>
698 <P>The <CODE>printers.cgi</CODE> program is responsible for
699 listing printer information, including jobs destined for that
700 printer. It is for all direct accesses to the <VAR>/printers</VAR> resource
701 and supports the optional form variables <CODE>OP</CODE> and
702 <CODE>WHICH_JOBS</CODE>. If no form variables are supplied then
703 the CGI lists all or a specific printer and the active jobs on
706 <P>The following <CODE>WHICH_JOBS</CODE> values are supported:
712 <DD>Show only the completed jobs.</DD>
714 <DT>not-completed</DT>
716 <DD>Show only the active jobs.</DD>
720 <P>The following <CODE>OP</CODE> values are supported:
724 <DT>print-test-page</DT>
726 <DD>Print a PostScript test page.</DD>
731 <EMBED SRC="glossary.shtml">