| <HTML> |
| <HEAD> |
| <META NAME="COPYRIGHT" CONTENT="Copyright 2001-2003, 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> |
