Thanks to its extensive use of templates, images, and message -catalogs, CUPS can be easily translated (or customized!) to suit -your needs. This help file will guide you through the CUPS -localization files so you can get the most out of it.
+Thanks to its extensive use of templates, images, and message catalogs, CUPS can be easily translated (or customized!) to suit your needs. This help file will guide you through the CUPS localization files so you can get the most out of it.
-Start by downloading the CUPS source code from www.cups.org. After you extract the files -from the source archive, you will want to copy the following -files and directories:
+Start by downloading the CUPS source code from www.cups.org. After you extract the files from the source archive (or clone the Git repository), you will want to copy the following files and directories:
With the exception of the message catalogs and desktop file, -localization files are placed in subdirectories under the -doc and templates using the locale name. -Locale names are either ll or ll_CC, where -"ll" is the 2-letter language code and "CC" is the 2-letter -country code. CUPS does not currently use or support the newer -ll-region syntax for locale names.
+With the exception of the message catalogs and desktop file, localization files are placed in subdirectories under the doc and templates using the locale name. Locale names are either ll or ll_CC, where "ll" is the 2-letter language code and "CC" is the 2-letter country code. CUPS does not currently use or support the newer ll-region syntax for locale names.
-All non-image files must be encoded using the UTF-8 character -set.
+All non-image files must be encoded using the UTF-8 character set.
-To submit a translation for inclusion in CUPS, translate the -desktop file, all of the template files, the index.html.in -file, and the message catalog. Place these files in the correct -subdirectories in the CUPS source code archive and run the following -command to create an archive with your files:
+To submit a translation for inclusion in CUPS, translate the desktop file, all of the template files, the index.html.in file, and the message catalog. Place these files in the correct subdirectories in the CUPS source code archive and run the following command to create an archive with your files:
-tar cvf ll_CC.tar.gz desktop/cups.desktop doc/ll_CC \ - locale/cups_ll_CC.po templates/ll_CC +tar cvf ll_CC.tar.gz desktop/cups.desktop doc/ll_CC locale/cups_ll_CC.po templates/ll_CC-
Replace "ll_CC" with the locale name for your translation. -Once you have created the archive, go to the CUPS Bugs -& Features page and submit a bug report, attaching the -translation to the report.
+Replace "ll_CC" with the locale name for your translation. Once you have created the archive, go to the CUPS project page and submit a bug report, attaching the translation to the report.
+Alternately, you can clone the CUPS project on Github, make your changes, and submit a pull request from the same link.
-The desktop/cups.desktop file provides a link to -the CUPS web interface from desktop environments such as -GNOME and KDE. To translate this file, add two lines to the -bottom with the Name and Comment keys:
+The desktop/cups.desktop file provides a link to the CUPS web interface from desktop environments such as GNOME and KDE. To translate this file, add two lines to the bottom with the Name and Comment keys:
Name[ll_CC]=Translation of "Manage Printing" @@ -82,42 +55,25 @@ Comment[ll_CC]=Translation of "CUPS Web Interface"-
The index.html file is a complete HTML file that is -displayed when the user visits "http://localhost:631/". Edit the -existing doc/index.html and save it in the -doc/ll_CC subdirectory so that the makefile can -install it. Run "make install" in the doc subdirectory -to test the new home page.
+The index.html.in file is a complete HTML file that is displayed when the user visits "http://localhost:631/". Edit the existing doc/index.html.in and save it in the doc/ll_CC subdirectory so that the configure script can generate it. After configuring, run "make install" in the doc subdirectory to test the new home page.
-CUPS message catalogs are GNU gettext ".po" text files that -provide a list of localized message strings for the CUPS -software. Message catalogs are named cups_ll.po or -cups_ll_CC.po, where "ll" is the standard 2-letter -abbreviation for the language and "CC" is the standard 2-letter -abbreviation for the country.
+CUPS message catalogs are GNU gettext ".po" text files that provide a list of localized message strings for the CUPS software. Message catalogs are named cups_ll.po or cups_ll_CC.po, where "ll" is the standard 2-letter abbreviation for the language and "CC" is the standard 2-letter abbreviation for the country.
-When translating a new message catalog, copy the -cups.pot message catalog file in the locale -subdirectory of the CUPS source code. For example, to start -translating the message catalog to Canadian French, you would -type the following commands:
+When translating a new message catalog, copy the cups.pot message catalog file in the locale subdirectory of the CUPS source code. For example, to start translating the message catalog to Canadian French, you would type the following commands:
cd locale cp cups.pot cups_fr_CA.po-
Alternatively, you can copy the existing cups_fr.po -message catalog and then make any necessary changes.
+Alternatively, you can copy the existing cups_fr.po message catalog and then make any necessary changes.
-Once you have make your copy of the file, edit it using your -favorite text editor or translation program to translate the text -to the desired language.
+Once you have make your copy of the file, edit it using your favorite text editor or translation program to translate the text to the desired language.
Then validate your translation using the locale/checkpo utility:
@@ -126,29 +82,14 @@ cd locale ./checkpo cups_ll_CC.po -After fixing any errors in your translation, add your locale to the LANGUAGES
-variable in the Makedefs file and run the "make
-install" command in the locale subdirectory to test
-the translation.
After fixing any errors in your translation, add your locale to the LANGUAGES variable in the Makedefs file and run the "make install" command in the locale subdirectory to test the translation. This variable is automatically updated when you run the configure script.
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.
+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.
-Template files are HTML files with special formatting
-characters in them that allow substitution of variables and arrays.
-The CUPS CGI programs (admin.cgi,
-classes.cgi, help.cgi,
-jobs.cgi, and printers.cgi) use these
-template file to provide dynamic content for the web interface.
-Template files are installed in the
-/usr/share/cups/templates directory by default. Table
-2 lists the various template files and their purpose.
Template files are HTML files with special formatting characters in them that allow substitution of variables and arrays. The CUPS CGI programs (admin.cgi, classes.cgi, help.cgi, jobs.cgi, and printers.cgi) use these template file to provide dynamic content for the web interface. Template files are installed in the /usr/share/cups/templates directory by default. Table 1 lists the various template files and their purpose.
Translated versions of the template files should be saved in the templates/ll_CC subdirectory. For example, @@ -159,8 +100,8 @@ translated all of the templates, add the locale to the Makedefs file and run "make install" in the templates subdirectory to test the translation.
-| Filename | @@ -170,17 +111,11 @@ translated all of the templates, add the locale to the|||
|---|---|---|---|
| add-class.tmpl | -This is the initial form that is shown to add a new - printer class. | +This is the initial form that is shown to add a new printer class. | |
| add-printer.tmpl | -This is the initial form that is shown to add a new - printer. | -||
| add-rss-subscription.tmpl | -This is the form that is shown to add a new RSS subscription. | +This is the initial form that is shown to add a new printer. | |
| admin.tmpl | @@ -188,28 +123,27 @@ translated all of the templates, add the locale to the|||
| choose-device.tmpl | -This is the form that shows the list of available - devices. | +This is the form that shows the list of available devices. | |
| choose-make.tmpl | -This is the form that shows the list of available - manufacturers. | +This is the form that shows the list of available manufacturers. | |
| choose-model.tmpl | -This is the form that shows the list of available - printer models/drivers. | +This is the form that shows the list of available printer models/drivers. | |
| choose-serial.tmpl | -This is the form that allows the user to choose - a serial port and any options. | +This is the form that allows the user to choose a serial port and any options. | |
| choose-uri.tmpl | -This is the form that allows the user to enter - a device URI for network printers. | +This is the form that allows the user to enter a device URI for network printers. | +|
| class.tmpl | +This template shows information about a single class. | ||
| class-added.tmpl | @@ -217,8 +151,7 @@ translated all of the templates, add the locale to the|||
| class-confirm.tmpl | -This is the template used to confirm the - deletion of a class. | +This is the template used to confirm the deletion of a class. | |
| class-deleted.tmpl | @@ -226,8 +159,7 @@ translated all of the templates, add the locale to the|||
| class-jobs-header.tmpl | -This template shows the "jobs" header for jobs in a - class. | +This template shows the "jobs" header for jobs in a class. | |
| class-modified.tmpl | @@ -239,8 +171,11 @@ translated all of the templates, add the locale to the|||
| classes-header.tmpl | -This template shows the "showing N of M classes" header in - the class list. | +This template shows the "showing N of M classes" header in the class list. | +|
| command.tmpl | +This template shows the status of a command job. | ||
| edit-config.tmpl | @@ -255,9 +190,8 @@ translated all of the templates, add the locale to theThis is the "unknown operation" error page. | ||
| header.tmpl | -This template is used as the standard header on all dynamic - content. | +header.tmpl(.in) | +This template is used as the standard header on all dynamic content. Edit the header.tmpl.in file and let the configure script generate the header.tmpl file. |
| help-header.tmpl | @@ -265,8 +199,11 @@ translated all of the templates, add the locale to the|||
| help-printable.tmpl | -This is the standard page header for the printable - version of help files. | +This is the standard page header for the printable version of help files. | +|
| help-trailer.tmpl | +This is the bottom part of the help page. | ||
| job-cancel.tmpl | @@ -294,36 +231,27 @@ translated all of the templates, add the locale to the|||
| jobs.tmpl | -This template is used to list the print jobs on a server, - class, or printer. | +This template is used to list the print jobs on a server, class, or printer. | |
| jobs-header.tmpl | -This template shows the "showing N or M jobs" header in the - jobs list. | +This template shows the "showing N or M jobs" header in the jobs list. | |
| list-available-printers.tmpl | This template shows a list of new printers that have been found. | ||
| maintenance.tmpl | -This template shows "maintenance commands sent". | -||
| modify-class.tmpl | -This template is used as the first form when modifying a - class. | +This template is used as the first form when modifying a class. | |
| modify-printer.tmpl | -This template is used as the first form when modifying a - printer. | +This template is used as the first form when modifying a printer. | |
| norestart.tmpl | -This template shows "server not restarted because no - changes were made to the configuration". | +This template shows "server not restarted because no changes were made to the configuration". | |
| option-boolean.tmpl | @@ -353,6 +281,10 @@ translated all of the templates, add the locale to thepager.tmpl | This template shows the previous/next pager bar. | |
| printer.tmpl | +This template shows information about a single printer. | +||
| printer-accept.tmpl | This template shows "printer now accepting jobs". | @@ -361,14 +293,17 @@ translated all of the templates, add the locale to theprinter-added.tmpl | This template shows "printer added". |
| printer-cancel-jobs.tmpl | +This template shows "All jobs on printer have been canceled." | +||
| printer-configured.tmpl | This template shows "printer configured". | ||
| printer-confirm.tmpl | -This template asks the user to confirm the deletion - of a printer. | +This template asks the user to confirm the deletion of a printer. | |
| printer-default.tmpl | @@ -380,8 +315,7 @@ translated all of the templates, add the locale to the|||
| printer-jobs-header.tmpl | -This templates shows the "jobs" header for jobs on a - printer. | +This templates shows the "jobs" header for jobs on a printer. | |
| printer-modified.tmpl | @@ -401,47 +335,27 @@ translated all of the templates, add the locale to the|||
| printers.tmpl | -This template is used to list information on one or more - printers. | +This template is used to list information on one or more printers. | |
| printers-header.tmpl | -This template shows the "showing printer N of M" header in - the printers list. | +This template shows the "showing printer N of M" header in the printers list. | |
| restart.tmpl | This template shows "server restarting". | ||
| samba-export.tmpl | -This template shows the export printers to Samba form. | -||
| samba-exported.tmpl | -This template shows "printers exported to Samba". | -||
| search.tmpl | This template shows the search form. | ||
| set-printer-options-header.tmpl | -This template shows the first part of the set printer options - form. | +This template shows the first part of the set printer options form. | |
| set-printer-options-trailer.tmpl | -This template shows the last part of the set printer options - form. | -||
| subscription-added.tmpl | -This template shows "subscription ... added". | -||
| subscription-canceled.tmpl | -This template shows "subscription #NNN canceled". | +This template shows the last part of the set printer options form. | |
| test-page.tmpl | @@ -449,8 +363,7 @@ translated all of the templates, add the locale to the|||
| trailer.tmpl | -This template is used as the standard trailer on all dynamic - content. | +This template is used as the standard trailer on all dynamic content. | |
| users.tmpl | @@ -459,42 +372,21 @@ translated all of the templates, add the locale to the
Template files consist of HTML with variable substitutions for -named inside curly braces "{name}". Variable names are generally -the IPP attribute names with the hyphen ("-") replaced by the -underscore ("_") character. For example, the -job-printer-uri attribute is renamed to -job_printer_uri.
+Template files consist of HTML with variable substitutions for named inside curly braces "{name}". Variable names are generally the IPP attribute names with the hyphen ("-") replaced by the underscore ("_") character. For example, the job-printer-uri attribute is renamed to job_printer_uri.
-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
-&name; mechanism or prefix each special
-character with the backslash ("\".)
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 &name; mechanism or prefix each special character with the backslash ("\".)
You substitute the value of a variable using
-{NAME} in your template file. If the variable is
-undefined then the {NAME} string is output
-as-is.
You substitute the value of a variable using {NAME} in your template file. If the variable is undefined then the {NAME} string is output as-is.
To substitute an empty string if the variable is undefined,
-use {?NAME} instead.
To substitute an empty string if the variable is undefined, use {?NAME} instead.
The number of array elements can be inserted using
-{#NAME}. If the array is undefined then 0 is output.
-The current array element (starting at 1) is inserted with
-{#}.
The number of array elements can be inserted using {#NAME}. If the array is undefined then 0 is output. The current array element (starting at 1) is inserted with {#}.
Arrays are handled using {[NAME] at the beginning
-of a section and } 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 job_id array:
Arrays are handled using {[NAME] at the beginning of a section and } 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 job_id array:
<TABLE>
@@ -514,13 +406,11 @@ in the job_id array:
</TABLE>
-Arrays can be nested, however all elements within the curly -braces ("{" and "}") are indexed using the innermost array.
+Arrays can be nested, however all elements within the curly braces ("{" and "}") are indexed using the innermost array.
-Templates can also test variables against specific values and -conditionally include text in the template. The format is:
+Templates can also test variables against specific values and conditionally include text in the template. The format is:
{variable?true:false}
@@ -530,15 +420,10 @@ conditionally include text in the template. The format is:
{variable>value?true:false}
-where true is the text that is included if the
-condition is true and false is the text that is
-included if the condition is false. A value of # is
-replaced with the current element number (starting at 1.) The
-character after the variable name specifies the condition to
-test. Table 3 shows the available test conditions.
where true is the text that is included if the condition is true and false is the text that is included if the condition is false. A value of # is replaced with the current element number (starting at 1.) The character after the variable name specifies the condition to test. Table 2 shows the available test conditions.
| Char | Condition | @@ -565,10 +450,29 @@ test. Table 3 shows the available test conditions.
|---|
Because HTML contains both markup (that generally is not localized) and text (which is localized), you should carefully avoid changing the markup unless it contains human-readable text. The following HTML examples show how to correctly localize template files:
+ +
+<!-- English table heading -->
+<table class="list" summary="Printer List">
+
+<!-- Correctly localized to French; the class attribute is unchanged but summary is localized -->
+<table class="list" summary="Liste des imprimantes">
+
+
+<!-- English hyperlink -->
+<li><a {SECTION=help?class="active" :}href="/help/">Help</a></li>
+
+<!-- Correctly localized to Danish; the href attribute is unchanged while the link text is localized -->
+<li><a {SECTION=help?class="active" :}href="/help/">Hjælp</a></li>
+
CUPS uses five CGI programs to manage the dynamic web -interfaces:
+CUPS uses five CGI programs to manage the dynamic web interfaces:
Each CGI program accepts standard form variables such as
-OP for the operation to perform,
-PRINTER_NAME for the printer or class name to
-operate on, QUERY for any search words,
-FIRST for the first class, job, or printer to
-display, and ORDER to control the order that
-classes, jobs, or printers are displayed.
In addition, the classes.cgi,
-jobs.cgi, and printers.cgi programs
-support a WHICH_JOBS variable to control which jobs
-are displayed. Table 4 lists the supported values.
| WHICH_JOBS Value | @@ -615,17 +510,12 @@ are displayed. Table 4 lists the supported values.
|---|
The admin.cgi program handles all of the printer
-and class administration functions and is run for all direct
-accesses to the /admin resource. For most operations
-it uses the PRINTER_NAME and OP form
-variables to specify the action requested. Table 5 shows the
-supported OP values.
The admin.cgi program handles all of the printer and class administration functions and is run for all direct accesses to the /admin resource. For most operations it uses the PRINTER_NAME and OP form variables to specify the action requested. Table 4 shows the supported OP values.
| OP Value | @@ -633,10 +523,6 @@ supported|||
|---|---|---|---|
| accept-jobs | -Accepts jobs on the named destination. | -||
| add-class | Adds a new printer class. | @@ -659,10 +545,6 @@ supportedDeletes a printer. The form variable CONFIRM
may be set to any value to bypass the confirmation page. |
|
| export-samba | -Exports printers to Samba. | -||
| find-new-printers | Find new printers that have not yet been added. | @@ -675,19 +557,11 @@ supportedmodify-printer | Modifies a printer. |
| purge-jobs | -Purges all jobs on the named destination. | -||
| redirect | Redirects the web browser to the location referenced by the URL form variable. | ||
| reject-jobs | -Rejects new jobs on the named destination. | -||
| set-allowed-users | Sets the allowed users for a destination. | @@ -704,38 +578,15 @@ supportedset-sharing | Sets the printer-is-shared attribute for a destination. |
| start-class | -Starts the named class. | -||
| start-printer | -Starts the named printer. | -||
| stop-class | -Stops the named class. | -||
| stop-printer | -Stops the named printer. | -
The classes.cgi program is responsible for
-listing class information, including jobs destined for that
-class. It is for all direct accesses to the /classes
-resource and supports the optional form variables OP
-and WHICH_JOBS. If no form variables are supplied
-then the CGI lists all or a specific class and the active jobs on
-each class. Table 6 shows the supported OP
-values.
The classes.cgi program is responsible for listing class information, including jobs destined for that class. It is for all direct accesses to the /classes resource and supports the optional form variables OP and WHICH_JOBS. If no form variables are supplied then the CGI lists all or a specific class and the active jobs on each class. Table 5 shows the supported OP values.
| OP Value | @@ -743,36 +594,49 @@ values.||
|---|---|---|
| accept-jobs | +Start accepting jobs for a class. | +|
| cancel-jobs | +Cancel all jobs for a class. | +|
| move-jobs | -Moves the jobs on this class to another destination. | +Move all jobs to a different destination. |
| print-test-page | -Prints the standard PostScript test page. | +Print a PostScript test page. | +
| reject-jobs | +Stop accepting jobs for a class. | +|
| start-class | +Start processing jobs for a class. | +|
| stop-class | +Stop processing jobs for a class. |
The help.cgi program handles all of the on-line
-help functions and is run for all direct accesses to the
-/help resource.
The help.cgi program handles all of the on-line help functions and is run for all direct accesses to the /help resource.
The jobs.cgi program handles all of the job
-functions and is run for all direct accesses to the
-/jobs resource. For most operations it uses the
-JOB_ID, OP, and WHICH_JOBS
-form variables to specify the action requested. Table 7 shows the
-supported OP values.
The jobs.cgi program handles all of the job functions and is run for all direct accesses to the /jobs resource. For most operations it uses the JOB_ID, OP, and WHICH_JOBS form variables to specify the action requested. Table 6 shows the supported OP values.
| OP Value | @@ -805,19 +669,12 @@ supported
|---|
The printers.cgi program is responsible for
-listing printer information, including jobs destined for that
-printer. It is for all direct accesses to the
-/printers resource and supports the optional form
-variables OP and WHICH_JOBS. If no form
-variables are supplied then the CGI lists all printers or a
-specific printer and the active jobs on that printer. Table 8
-shows the supported OP values.
The printers.cgi program is responsible for listing printer information, including jobs destined for that printer. It is for all direct accesses to the /printers resource and supports the optional form variables OP and WHICH_JOBS. If no form variables are supplied then the CGI lists all printers or a specific printer and the active jobs on that printer. Table 7 shows the supported OP values.
| OP Value | @@ -825,6 +682,14 @@ shows the supported|||
|---|---|---|---|
| accept-jobs | +Start accepting jobs for a printer. | +||
| cancel-jobs | +Cancel all jobs for a printer. | +||
| clean-print-heads | Clean the print heads. | @@ -841,6 +706,18 @@ shows the supportedprint-test-page | Print a PostScript test page. |
| reject-jobs | +Stop accepting jobs for a printer. | +||
| start-printer | +Start processing jobs for a printer. | +||
| stop-printer | +Stop processing jobs for a printer. | +