<HTML>
<HEAD>
<META NAME="COPYRIGHT" CONTENT="Copyright 2001-2005, All Rights Reserved">
<META NAME="DOCNUMBER" CONTENT="CUPS-TRANS-1.1">
<META NAME="Author" CONTENT="Easy Software Products">
<TITLE>CUPS Translation Guide</TITLE>
</HEAD>
<BODY>
<H1>Scope</H1>
<H2>Identification</H2>
<P>This translation guide provides instructions for creating
translations of the CUPS message catalogs and web pages for the
Common UNIX Printing System ("CUPS") Version 1.1 software.
<EMBED SRC="system-overview.shtml">
<H2>Document Overview</H2>
<P>This translation guide is organized into the following
sections:
<UL>
<LI>1 - Scope</LI>
<LI>2 - References</LI>
<LI>3 - Character Sets</LI>
<LI>4 - Message Catalogs</LI>
<LI>5 - Web Interfaces</LI>
<LI>A - Glossary</LI>
</UL>
<EMBED SRC="references.shtml">
<H1>Character Sets</H1>
<P>CUPS uses character set files to define the mapping of local
character sets to Unicode code points, as well as the fonts that
should be used for different ranges of characters.
<P>CUPS includes files for common 8-bit encodings as well as
UTF-8 for Unicode text. The format of these files is described
in the CUPS Interface Design Description (IDD) document.
Current character sets are enumerated in the CUPS API, so in
order to add a new character set you must patch the CUPS source
as well as provide a new charset file.
<P>CUPS 1.1 supports the following character sets:
<UL>
<LI>iso-8859-1
<LI>iso-8859-2
<LI>iso-8859-3
<LI>iso-8859-4
<LI>iso-8859-5
<LI>iso-8859-6
<LI>iso-8859-7
<LI>iso-8859-8
<LI>iso-8859-9
<LI>iso-8859-10
<LI>iso-8859-13
<LI>iso-8859-14
<LI>iso-8859-15
<LI>koi8-r
<LI>koi8-u
<LI>us-ascii
<LI>utf-8
<LI>windows-874
<LI>windows-1250
<LI>windows-1251
<LI>windows-1252
<LI>windows-1253
<LI>windows-1254
<LI>windows-1255
<LI>windows-1256
<LI>windows-1257
<LI>windows-1258
</UL>
<H1>Message Catalogs</H1>
<P>CUPS message catalogs are text files that identify the
default character set for the locale and a list of localized
message strings for the CUPS software. The format of the
message catalog files is described in the CUPS IDD.
<P>Message catalogs are named <VAR>cups_ll</VAR>,
<VAR>cups_ll_CC</VAR>, or <VAR>cups_ll_CC.charset</VAR>, where
"ll" is the standard 2-letter abbreviation for the language,
"CC" is the standard 2-letter abbreviation for the country, and
"charset" is the charset name which may differ from the list
above.
<P>Each message catalog file is stored in a subdirectory named
<VAR>ll</VAR>, <VAR>ll_CC</VAR>, or <VAR>ll_CC.charset</VAR> to
match the trailing portion of the message catalog filename.
<P>When translating a new message catalog, copy the <VAR>cups_C</VAR>
message catalog file to a new subdirectory; to translate the
message catalog to Canadian French, you would type the following
commands:
<UL><PRE>
<KBD>cd locale <I>ENTER</I></KBD>
<KBD>mkdir fr_CA <I>ENTER</I></KBD>
<KBD>cp C/cups_C fr_CA/cups_fr_CA <I>ENTER</I></KBD>
</PRE></UL>
<P>Alternatively, you could copy the existing <VAR>cups_fr</VAR>
message catalog and then make any changes necessary.
<P>Once you have make your copy of the file, edit it using your
favorite text editor to translate the text to the desired
language. Be sure to preserve any numbers starting in the first
column, as they indicate a new message number - you'll see this
for the HTTP status messages.
<P>Finally, add your locale to the list of locales in the
makefile and run the following command to install it:
<UL><PRE>
<KBD>make install <I>ENTER</I></KBD>
</PRE></UL>
<H1>Web Interfaces</H1>
<P>The CUPS scheduler provides a web interface that can be used
to do many common printing and administration tasks. The built-in
web server supports localization of web pages through the use of
subdirectories for each locale, e.g. "fr" for French, "de" for
German, "fr_ca" for French in Canada, and so forth.
<H2>Template Files</H2>
<P>Template files are HTML files with special formatting
characters in them that allow substition of variables and
arrays. The CUPS CGI programs (<CODE>admin.cgi</CODE>,
<CODE>classes.cgi</CODE>, <CODE>jobs.cgi</CODE>, and
<CODE>printers.cgi</CODE>) use these template file to provide
dynamic content for the web interface. Template files are
installed in the <VAR>/usr/share/cups/templates</VAR> directory
by default.
<P>Translated versions of the template files should be installed
in the appropriate subdirectories under
<VAR>/usr/share/cups/templates</VAR>. For example, Canadian
French template files should be stored in the
<VAR>/usr/share/cups/templates/fr_CA</VAR> directory.
<H3>Inserting Attributes and Values</H3>
<P>Template files consist of HTML with variable substitutions
for named inside curley braces "{name}". Variable names are
generally the IPP attribute names with the hyphen ("-") replaced
by the underscore ("_") character. For example, the
<TT>job-printer-uri</TT> attribute is renamed to
<TT>job_printer_uri</TT>.
<P>Curley braces ("{" and "}") to indicate substitutions, and
the backslash ("\") character for quoting. To insert any of
these special characters as-is you need to use the HTML
<CODE>&name;</CODE> mechanism or prefix each special
character with the backslash ("\".)</P>
<P>You substitute the value of a variable using
<CODE>{NAME}</CODE> in your template file. If the variable is
undefined then the <CODE>{NAME}</CODE> string is output
as-is.</P>
<P>To substitute an empty string if the variable is undefined, use
<CODE>{?NAME}</CODE> instead.</P>
<H3>Array Substitutions</H3>
<P>The number of array elements can be inserted using
<CODE>{#NAME}</CODE>. If the array is undefined then 0 is
output. The current array element (starting at 1) is inserted
with <CODE>{#}</CODE>.</P>
<P>Arrays are handled using <CODE>{[NAME]</CODE> at the beginning of a
section and <CODE>}</CODE> at the end. The information between the closing
bracket ("]") and closing brace ("}") is repeated for as many elements as
are in the named array. For example, the following template will display
a list of each job in the <CODE>job_id</CODE> array:</P>
<UL><PRE>
<TABLE>
<TR>
<TH>Job ID</TH>
<TH>Destination</TH>
<TH>Title</TH>
</TR>
{[job_id]
<TR>
<TD>{?job_id}</TD>
<TD>{?job_printer_name}</TD>
<TD>{?job_name}</TD>
</TR>
}
</TABLE>
</PRE></UL>
<P>Arrays can be nested, however all elements within the curley
braces ("{" and "}") are indexed using the innermost array.</P>
<H3>Conditional Tests</H3>
<P>Templates can also test variables against specific values and
conditionally include text in the template. The format is:
<UL><PRE>
{<I>variable</I>?<I>true</I>:<I>false</I>}
{<I>variable</I>=<I>value</I>?<I>true</I>:<I>false</I>}
{<I>variable</I>!<I>value</I>?<I>true</I>:<I>false</I>}
{<I>variable</I><<I>value</I>?<I>true</I>:<I>false</I>}
{<I>variable</I>><I>value</I>?<I>true</I>:<I>false</I>}
</PRE></UL>
<P>where <VAR>true</VAR> is the text that is included if the
condition is true and <VAR>false</VAR> is the text that is
included if the condition is false. A value of <CODE>#</CODE> is
replaced with the current element number (starting at 1.)
<P>The character after the variable name specifies the condition
to test:
<CENTER><TABLE BORDER="1">
<TR>
<TH WIDTH="5%">Char</TH>
<TH WIDTH="50%">Condition</TH>
</TR>
<TR>
<TD>?</TD>
<TD>True if <VAR>variable</VAR> exists.</TD>
</TR>
<TR>
<TD>=</TD>
<TD>True if <VAR>variable</VAR> is equal to <VAR>value</VAR>.</TD>
</TR>
<TR>
<TD>!</TD>
<TD>True if <VAR>variable</VAR> is not equal to <VAR>value</VAR>.</TD>
</TR>
<TR>
<TD><</TD>
<TD>True if <VAR>variable</VAR> is less than <VAR>value</VAR>.</TD>
</TR>
<TR>
<TD>></TD>
<TD>True if <VAR>variable</VAR> is greater than <VAR>value</VAR>.</TD>
</TR>
</TABLE></CENTER>
<H3>Template File List</H3>
<P>The following template files are used by the web interface:
<DL>
<DT>add-class.tmpl
<DD>This is the initial form that is shown to add a new
printer class.
<DT>add-printer.tmpl
<DD>This is the initial form that is shown to add a new
printer.
<DT>admin-op.tmpl
<DD>This is the template that is used to display an error
message when the admin interface sees an undefined
operation name.
<DT>admin.tmpl
<DD>This is the template that shows the initial menu of
operations (add a class, manage classes, etc.)
<DT>choose-device.tmpl
<DD>This is the form that shows the list of available
devices.
<DT>choose-make.tmpl
<DD>This is the form that shows the list of available
manufacturers.
<DT>choose-members.tmpl
<DD>This is the form that shows the list of available
printers that can be added to a class.
<DT>choose-model.tmpl
<DD>This is the form that shows the list of available
printer models/drivers.
<DT>choose-serial.tmpl
<DD>This is the form that allows the user to choose
a serial port and any options.
<DT>choose-uri.tmpl
<DD>This is the form that allows the user to enter
a device URI for network printers.
<DT>class-added.tmpl
<DD>This template shows the "class added" message.
<DT>class-confirm.tmpl
<DD>This is the template used to confirm the
deletion of a class.
<DT>class-deleted.tmpl
<DD>This template shows the "class deleted" message.
<DT>classes.tmpl
<DD>This template shows one or more printer classes.
<DT>class-modified.tmpl
<DD>This template shows the "class modified" message.
<DT>config-printer.tmpl
<DD>This template starts the printer configuration form.
<DT>config-printer2.tmpl
<DD>This template ends the printer configuration form.
<DT>error.tmpl
<DD>This template displays a generic error message.
<DT>header.tmpl
<DD>This template is used as the standard header on all dynamic
content.
<DT>job-cancel.tmpl
<DD>This template shows "job cancelled".
<DT>job-hold.tmpl
<DD>This template shows "job held".
<DT>job-op.tmpl
<DD>This is the template that is used to display an
error message when the job interface sees an undefined
operation name.
<DT>job-release.tmpl
<DD>This template shows "job released".
<DT>job-restart.tmpl
<DD>This template shows "job restarted".
<DT>jobs.tmpl
<DD>This template is used to list the print jobs on a server,
class, or printer.
<DT>modify-class.tmpl
<DD>This template is used as the first form when modifying a
class.
<DT>modify-printer.tmpl
<DD>This template is used as the first form when modifying a
printer.
<DT>option-boolean.tmpl
<DD>This template is used to select a boolean PPD option.
<DT>option-header.tmpl
<DD>This template is used to start a PPD option group.
<DT>option-pickmany.tmpl
<DD>This template is used to select a multi-valued PPD option.
<DT>option-pickone.tmpl
<DD>This template is used to select a single-valued PPD option.
<DT>option-trailer.tmpl
<DD>This template is used to end a PPD option group.
<DT>printer-accept.tmpl
<DD>This template shows "printer now accepting jobs".
<DT>printer-added.tmpl
<DD>This template shows "printer added".
<DT>printer-configured.tmpl
<DD>This template shows "printer configured".
<DT>printer-confirm.tmpl
<DD>This template asks the user to confirm the deletion of a printer.
<DT>printer-deleted.tmpl
<DD>This template shows "printer deleted".
<DT>printer-modified.tmpl
<DD>This template shows "printer modified".
<DT>printer-purge.tmpl
<DD>This template shows "printer has been purged of all jobs".
<DT>printer-reject.tmpl
<DD>This template shows "printer now rejecting jobs".
<DT>printer-start.tmpl
<DD>This template shows "printer started".
<DT>printers.tmpl
<DD>This template is used to list information on one or more
printers.
<DT>printer-stop.tmpl
<DD>This template shows "printer stopped".
<DT>test-page.tmpl
<DD>This template shows "test page printed".
<DT>trailer.tmpl
<DD>This template is used as the standard trailer on all dynamic
content.
</DL>
<H2>CGI Programs</H2>
<P>CUPS uses four CGI programs to manage the dynamic web interfaces:
<UL>
<LI><CODE>admin.cgi</CODE></LI>
<LI><CODE>classes.cgi</CODE></LI>
<LI><CODE>jobs.cgi</CODE></LI>
<LI><CODE>printers.cgi</CODE></LI>
</UL>
<H3>admin.cgi</H3>
<P>The <CODE>admin.cgi</CODE> program handles all of the printer
and class administration functions and is run for all direct
accesses to the <VAR>/admin</VAR> resource. For most operations it uses the
<CODE>PRINTER_NAME</CODE> and <CODE>OP</CODE> form variables to
specify the action requested.
<P>The following <CODE>OP</CODE> values are supported:
<DL>
<DT>accept-jobs</DT>
<DD>Accepts jobs on the named destination.</DD>
<DT>add-class</DT>
<DD>Adds a new printer class. This operation also adds
several other form variables:
<DL>
<DT>MEMBER_URIS</DT>
<DD>Sets the members of the class. Multiple
<CODE>MEMBER_URIS</CODE> values can be
provided.</DD>
<DT>PRINTER_INFO</DT>
<DD>Sets the printer-info attribute for the
printer class, which is usually the printer
description.</DD>
<DT>PRINTER_LOCATION</DT>
<DD>Sets the printer-location attribute for the
printer class.</DD>
</DL>
</DD>
<DT>add-printer</DT>
<DD>Adds a new printer. This operation also adds several other
form variables:
<DL>
<DT>BAUDRATE</DT>
<DD>Sets the baud rate for serial devices.</DD>
<DT>BITS</DT>
<DD>Sets the number of data bits for serial devices.</DD>
<DT>DEVICE_URI</DT>
<DD>Sets the device URI for the printer.</DD>
<DT>FLOW</DT>
<DD>Sets the flow control for serial devices.</DD>
<DT>PARITY</DT>
<DD>Sets the parity checking for serial devices.</DD>
<DT>PPD_NAME</DT>
<DD>Sets the driver name for the printer ("raw" for a
raw queue.)</DD>
<DT>PRINTER_INFO</DT>
<DD>Sets the printer-info attribute for the
printer, which is usually the printer
description.</DD>
<DT>PRINTER_LOCATION</DT>
<DD>Sets the printer-location attribute for the
printer.</DD>
</DL>
</DD>
<DT>config-printer</DT>
<DD>Configures an existing printer. This operation uses
form variables of the same name as the options in the
printer's PPD file.</DD>
<DT>delete-class</DT>
<DD>Deletes a printer class. The form variable <CODE>CONFIRM</CODE>
may be set to any value to bypass the confirmation page.</DD>
<DT>delete-printer</DT>
<DD>Deletes a printer. The form variable <CODE>CONFIRM</CODE>
may be set to any value to bypass the confirmation page.</DD>
<DT>modify-class</DT>
<DD>Modifies a printer class. See the add-class operation for a
list of form variables.</DD>
<DT>modify-printer</DT>
<DD>Modifies a printer. See the add-printer operation for a
list of form variables.</DD>
<DT>purge-jobs</DT>
<DD>Purges all jobs on the named destination.</DD>
<DT>reject-jobs</DT>
<DD>Rejects new jobs on the named destination.</DD>
<DT>start-printer</DT>
<DD>Starts the named destination.</DD>
<DT>stop-printer</DT>
<DD>Stops the named destination.</DD>
</DL>
<H3>classes.cgi</H3>
<P>The <CODE>classes.cgi</CODE> program is responsible for
listing class information, including jobs destined for that
class. It is for all direct accesses to the <VAR>/classes</VAR> resource
and supports the optional form variables <CODE>OP</CODE> and
<CODE>WHICH_JOBS</CODE>. If no form variables are supplied then
the CGI lists all or a specific class and the active jobs on
each class.
<P>The following <CODE>WHICH_JOBS</CODE> values are supported:
<DL>
<DT>completed</DT>
<DD>Show only the completed jobs.</DD>
<DT>not-completed</DT>
<DD>Show only the active jobs.</DD>
</DL>
<P>The following <CODE>OP</CODE> values are supported:
<DL>
<DT>print-test-page</DT>
<DD>Print a PostScript test page.</DD>
</DL>
<H3>jobs.cgi</H3>
<P>The <CODE>jobs.cgi</CODE> program handles all of the job
functions and is run for all direct accesses to the <VAR>/jobs</VAR>
resource. For most operations it uses the
<CODE>JOB_ID</CODE>, <CODE>OP</CODE>, and
<CODE>WHICH_JOBS</CODE> form variables to specify the action
requested.
<P>The following <CODE>WHICH_JOBS</CODE> values are supported:
<DL>
<DT>completed</DT>
<DD>Show only the completed jobs.</DD>
<DT>not-completed</DT>
<DD>Show only the active jobs.</DD>
</DL>
<P>The following <CODE>OP</CODE> values are supported:
<DL>
<DT>job-cancel</DT>
<DD>Cancels a job.</DD>
<DT>job-hold</DT>
<DD>Holds a job indefinitely.</DD>
<DT>job-release</DT>
<DD>Releases a job for printing.</DD>
<DT>job-restart</DT>
<DD>Restarts a stopped, cancelled, completed, or aborted
print job.</DD>
</DL>
<H3>printers.cgi</H3>
<P>The <CODE>printers.cgi</CODE> program is responsible for
listing printer information, including jobs destined for that
printer. It is for all direct accesses to the <VAR>/printers</VAR> resource
and supports the optional form variables <CODE>OP</CODE> and
<CODE>WHICH_JOBS</CODE>. If no form variables are supplied then
the CGI lists all or a specific printer and the active jobs on
each printer.
<P>The following <CODE>WHICH_JOBS</CODE> values are supported:
<DL>
<DT>completed</DT>
<DD>Show only the completed jobs.</DD>
<DT>not-completed</DT>
<DD>Show only the active jobs.</DD>
</DL>
<P>The following <CODE>OP</CODE> values are supported:
<DL>
<DT>print-test-page</DT>
<DD>Print a PostScript test page.</DD>
</DL>
<EMBED SRC="glossary.shtml">
</BODY>
</HTML>