doc/translation.shtml

   1 <HTML>
   2 <HEAD>
   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>
   7 </HEAD>
   8 <BODY>
   9
  10 <H1>Scope</H1>
  11
  12 <H2>Identification</H2>
  13
  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.
  17
  18 <EMBED SRC="system-overview.shtml">
  19
  20 <H2>Document Overview</H2>
  21
  22 <P>This translation guide is organized into the following
  23 sections:
  24
  25 <UL>
  26         <LI>1 - Scope</LI>
  27         <LI>2 - References</LI>
  28         <LI>3 - Character Sets</LI>
  29         <LI>4 - Message Catalogs</LI>
  30         <LI>5 - Web Interfaces</LI>
  31         <LI>A - Glossary</LI>
  32 </UL>
  33
  34 <EMBED SRC="references.shtml">
  35
  36
  37 <H1>Character Sets</H1>
  38
  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.
  42
  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.
  49
  50 <P>CUPS 1.1 supports the following character sets:
  51
  52 <UL>
  53
  54         <LI>iso-8859-1
  55         <LI>iso-8859-2
  56         <LI>iso-8859-3
  57         <LI>iso-8859-4
  58         <LI>iso-8859-5
  59         <LI>iso-8859-6
  60         <LI>iso-8859-7
  61         <LI>iso-8859-8
  62         <LI>iso-8859-9
  63         <LI>iso-8859-10
  64         <LI>iso-8859-13
  65         <LI>iso-8859-14
  66         <LI>iso-8859-15
  67         <LI>koi8-r
  68         <LI>koi8-u
  69         <LI>us-ascii
  70         <LI>utf-8
  71         <LI>windows-874
  72         <LI>windows-1250
  73         <LI>windows-1251
  74         <LI>windows-1252
  75         <LI>windows-1253
  76         <LI>windows-1254
  77         <LI>windows-1255
  78         <LI>windows-1256
  79         <LI>windows-1257
  80         <LI>windows-1258
  81
  82 </UL>
  83
  84 <H1>Message Catalogs</H1>
  85
  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.
  90
  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
  96 above.
  97
  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.
 101
 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
 105 commands:
 106
 107 <UL><PRE>
 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>
 111 </PRE></UL>
 112
 113 <P>Alternatively, you could copy the existing <VAR>cups_fr</VAR>
 114 message catalog and then make any changes necessary.
 115
 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.
 121
 122 <P>Finally, add your locale to the list of locales in the
 123 makefile and run the following command to install it:
 124
 125 <UL><PRE>
 126 <KBD>make install <I>ENTER</I></KBD>
 127 </PRE></UL>
 128
 129 <H1>Web Interfaces</H1>
 130
 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.
 136
 137 <H2>Template Files</H2>
 138
 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
 146 by default.
 147
 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.
 153
 154 <H3>Inserting Attributes and Values</H3>
 155
 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>.
 162
 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>&amp;name;</CODE> mechanism or prefix each special
 167 character with the backslash ("\".)</P>
 168
 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
 172 as-is.</P>
 173
 174 <P>To substitute an empty string if the variable is undefined, use
 175 <CODE>{?NAME}</CODE> instead.</P>
 176
 177 <H3>Array Substitutions</H3>
 178
 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>
 183
 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>
 189
 190 <UL><PRE>
 191 &lt;TABLE&gt;
 192 &lt;TR&gt;
 193         &lt;TH&gt;Job ID&lt;/TH&gt;
 194         &lt;TH&gt;Destination&lt;/TH&gt;
 195         &lt;TH&gt;Title&lt;/TH&gt;
 196 &lt;/TR&gt;
 197
 198 {[job_id]
 199 &lt;TR&gt;
 200         &lt;TD&gt;{?job_id}&lt;/TD&gt;
 201         &lt;TD&gt;{?job_printer_name}&lt;/TD&gt;
 202         &lt;TD&gt;{?job_name}&lt;/TD&gt;
 203 &lt;/TR&gt;
 204 }
 205 &lt;/TABLE&gt;
 206 </PRE></UL>
 207
 208 <P>Arrays can be nested, however all elements within the curley
 209 braces ("{" and "}") are indexed using the innermost array.</P>
 210
 211 <H3>Conditional Tests</H3>
 212
 213 <P>Templates can also test variables against specific values and
 214 conditionally include text in the template. The format is:
 215
 216 <UL><PRE>
 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>&lt;<I>value</I>?<I>true</I>:<I>false</I>}
 221 {<I>variable</I>><I>value</I>?<I>true</I>:<I>false</I>}
 222 </PRE></UL>
 223
 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.)
 228
 229 <P>The character after the variable name specifies the condition
 230 to test:
 231
 232 <CENTER><TABLE BORDER="1">
 233 <TR>
 234         <TH WIDTH="5%">Char</TH>
 235         <TH WIDTH="50%">Condition</TH>
 236 </TR>
 237 <TR>
 238         <TD>?</TD>
 239         <TD>True if <VAR>variable</VAR> exists.</TD>
 240 </TR>
 241 <TR>
 242         <TD>=</TD>
 243         <TD>True if <VAR>variable</VAR> is equal to <VAR>value</VAR>.</TD>
 244 </TR>
 245 <TR>
 246         <TD>!</TD>
 247         <TD>True if <VAR>variable</VAR> is not equal to <VAR>value</VAR>.</TD>
 248 </TR>
 249 <TR>
 250         <TD>&lt;</TD>
 251         <TD>True if <VAR>variable</VAR> is less than <VAR>value</VAR>.</TD>
 252 </TR>
 253 <TR>
 254         <TD>></TD>
 255         <TD>True if <VAR>variable</VAR> is greater than <VAR>value</VAR>.</TD>
 256 </TR>
 257 </TABLE></CENTER>
 258
 259 <H3>Template File List</H3>
 260
 261 <P>The following template files are used by the web interface:
 262
 263 <DL>
 264
 265 <DT>add-class.tmpl
 266
 267         <DD>This is the initial form that is shown to add a new
 268         printer class.
 269
 270 <DT>add-printer.tmpl
 271
 272         <DD>This is the initial form that is shown to add a new
 273         printer.
 274
 275 <DT>admin-op.tmpl
 276
 277         <DD>This is the template that is used to display an error
 278         message when the admin interface sees an undefined
 279         operation name.
 280
 281 <DT>admin.tmpl
 282
 283         <DD>This is the template that shows the initial menu of
 284         operations (add a class, manage classes, etc.)
 285
 286 <DT>choose-device.tmpl
 287
 288         <DD>This is the form that shows the list of available
 289         devices.
 290
 291 <DT>choose-make.tmpl
 292
 293         <DD>This is the form that shows the list of available
 294         manufacturers.
 295
 296 <DT>choose-members.tmpl
 297
 298         <DD>This is the form that shows the list of available
 299         printers that can be added to a class.
 300
 301 <DT>choose-model.tmpl
 302
 303         <DD>This is the form that shows the list of available
 304         printer models/drivers.
 305
 306 <DT>choose-serial.tmpl
 307
 308         <DD>This is the form that allows the user to choose
 309         a serial port and any options.
 310
 311 <DT>choose-uri.tmpl
 312
 313         <DD>This is the form that allows the user to enter
 314         a device URI for network printers.
 315
 316 <DT>class-added.tmpl
 317
 318         <DD>This template shows the "class added" message.
 319
 320 <DT>class-confirm.tmpl
 321
 322         <DD>This is the template used to confirm the
 323         deletion of a class.
 324
 325 <DT>class-deleted.tmpl
 326
 327         <DD>This template shows the "class deleted" message.
 328
 329 <DT>classes.tmpl
 330
 331         <DD>This template shows one or more printer classes.
 332
 333 <DT>class-modified.tmpl
 334
 335         <DD>This template shows the "class modified" message.
 336
 337 <DT>config-printer.tmpl
 338
 339         <DD>This template starts the printer configuration form.
 340
 341 <DT>config-printer2.tmpl
 342
 343         <DD>This template ends the printer configuration form.
 344
 345 <DT>error.tmpl
 346
 347         <DD>This template displays a generic error message.
 348
 349 <DT>header.tmpl
 350
 351         <DD>This template is used as the standard header on all dynamic
 352         content.
 353
 354 <DT>job-cancel.tmpl
 355
 356         <DD>This template shows "job cancelled".
 357
 358 <DT>job-hold.tmpl
 359
 360         <DD>This template shows "job held".
 361
 362 <DT>job-op.tmpl
 363
 364         <DD>This is the template that is used to display an
 365         error message when the job interface sees an undefined
 366         operation name.
 367
 368 <DT>job-release.tmpl
 369
 370         <DD>This template shows "job released".
 371
 372 <DT>job-restart.tmpl
 373
 374         <DD>This template shows "job restarted".
 375
 376 <DT>jobs.tmpl
 377
 378         <DD>This template is used to list the print jobs on a server,
 379         class, or printer.
 380
 381 <DT>modify-class.tmpl
 382
 383         <DD>This template is used as the first form when modifying a
 384         class.
 385
 386 <DT>modify-printer.tmpl
 387
 388         <DD>This template is used as the first form when modifying a
 389         printer.
 390
 391 <DT>option-boolean.tmpl
 392
 393         <DD>This template is used to select a boolean PPD option.
 394
 395 <DT>option-header.tmpl
 396
 397         <DD>This template is used to start a PPD option group.
 398
 399 <DT>option-pickmany.tmpl
 400
 401         <DD>This template is used to select a multi-valued PPD option.
 402
 403 <DT>option-pickone.tmpl
 404
 405         <DD>This template is used to select a single-valued PPD option.
 406
 407 <DT>option-trailer.tmpl
 408
 409         <DD>This template is used to end a PPD option group.
 410
 411 <DT>printer-accept.tmpl
 412
 413         <DD>This template shows "printer now accepting jobs".
 414
 415 <DT>printer-added.tmpl
 416
 417         <DD>This template shows "printer added".
 418
 419 <DT>printer-configured.tmpl
 420
 421         <DD>This template shows "printer configured".
 422
 423 <DT>printer-confirm.tmpl
 424
 425         <DD>This template asks the user to confirm the deletion of a printer.
 426
 427 <DT>printer-deleted.tmpl
 428
 429         <DD>This template shows "printer deleted".
 430
 431 <DT>printer-modified.tmpl
 432
 433         <DD>This template shows "printer modified".
 434
 435 <DT>printer-purge.tmpl
 436
 437         <DD>This template shows "printer has been purged of all jobs".
 438
 439 <DT>printer-reject.tmpl
 440
 441         <DD>This template shows "printer now rejecting jobs".
 442
 443 <DT>printer-start.tmpl
 444
 445         <DD>This template shows "printer started".
 446
 447 <DT>printers.tmpl
 448
 449         <DD>This template is used to list information on one or more
 450         printers.
 451
 452 <DT>printer-stop.tmpl
 453
 454         <DD>This template shows "printer stopped".
 455
 456 <DT>test-page.tmpl
 457
 458         <DD>This template shows "test page printed".
 459
 460 <DT>trailer.tmpl
 461
 462         <DD>This template is used as the standard trailer on all dynamic
 463         content.
 464
 465 </DL>
 466
 467 <H2>CGI Programs</H2>
 468
 469 <P>CUPS uses four CGI programs to manage the dynamic web interfaces:
 470
 471 <UL>
 472
 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>
 477
 478 </UL>
 479
 480 <H3>admin.cgi</H3>
 481
 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.
 487
 488 <P>The following <CODE>OP</CODE> values are supported:
 489
 490 <DL>
 491
 492 <DT>accept-jobs</DT>
 493
 494         <DD>Accepts jobs on the named destination.</DD>
 495
 496 <DT>add-class</DT>
 497
 498         <DD>Adds a new printer class. This operation also adds
 499         several other form variables:
 500
 501         <DL>
 502
 503         <DT>MEMBER_URIS</DT>
 504
 505                 <DD>Sets the members of the class. Multiple
 506                 <CODE>MEMBER_URIS</CODE> values can be
 507                 provided.</DD>
 508
 509         <DT>PRINTER_INFO</DT>
 510
 511                 <DD>Sets the printer-info attribute for the
 512                 printer class, which is usually the printer
 513                 description.</DD>
 514
 515         <DT>PRINTER_LOCATION</DT>
 516
 517                 <DD>Sets the printer-location attribute for the
 518                 printer class.</DD>
 519
 520         </DL>
 521
 522         </DD>
 523
 524 <DT>add-printer</DT>
 525
 526         <DD>Adds a new printer. This operation also adds several other
 527         form variables:
 528
 529         <DL>
 530
 531         <DT>BAUDRATE</DT>
 532
 533                 <DD>Sets the baud rate for serial devices.</DD>
 534
 535         <DT>BITS</DT>
 536
 537                 <DD>Sets the number of data bits for serial devices.</DD>
 538
 539         <DT>DEVICE_URI</DT>
 540
 541                 <DD>Sets the device URI for the printer.</DD>
 542
 543         <DT>FLOW</DT>
 544
 545                 <DD>Sets the flow control for serial devices.</DD>
 546
 547         <DT>PARITY</DT>
 548
 549                 <DD>Sets the parity checking for serial devices.</DD>
 550
 551         <DT>PPD_NAME</DT>
 552
 553                 <DD>Sets the driver name for the printer ("raw" for a
 554                 raw queue.)</DD>
 555
 556         <DT>PRINTER_INFO</DT>
 557
 558                 <DD>Sets the printer-info attribute for the
 559                 printer, which is usually the printer
 560                 description.</DD>
 561
 562         <DT>PRINTER_LOCATION</DT>
 563
 564                 <DD>Sets the printer-location attribute for the
 565                 printer.</DD>
 566
 567         </DL>
 568
 569         </DD>
 570
 571 <DT>config-printer</DT>
 572
 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>
 576
 577 <DT>delete-class</DT>
 578
 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>
 581
 582 <DT>delete-printer</DT>
 583
 584         <DD>Deletes a printer. The form variable <CODE>CONFIRM</CODE>
 585         may be set to any value to bypass the confirmation page.</DD>
 586
 587 <DT>modify-class</DT>
 588
 589         <DD>Modifies a printer class. See the add-class operation for a
 590         list of form variables.</DD>
 591
 592 <DT>modify-printer</DT>
 593
 594         <DD>Modifies a printer. See the add-printer operation for a
 595         list of form variables.</DD>
 596
 597 <DT>purge-jobs</DT>
 598
 599         <DD>Purges all jobs on the named destination.</DD>
 600
 601 <DT>reject-jobs</DT>
 602
 603         <DD>Rejects new jobs on the named destination.</DD>
 604
 605 <DT>start-printer</DT>
 606
 607         <DD>Starts the named destination.</DD>
 608
 609 <DT>stop-printer</DT>
 610
 611         <DD>Stops the named destination.</DD>
 612
 613 </DL>
 614
 615
 616 <H3>classes.cgi</H3>
 617
 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
 624 each class.
 625
 626 <P>The following <CODE>WHICH_JOBS</CODE> values are supported:
 627
 628 <DL>
 629
 630 <DT>completed</DT>
 631
 632         <DD>Show only the completed jobs.</DD>
 633
 634 <DT>not-completed</DT>
 635
 636         <DD>Show only the active jobs.</DD>
 637
 638 </DL>
 639
 640 <P>The following <CODE>OP</CODE> values are supported:
 641
 642 <DL>
 643
 644 <DT>print-test-page</DT>
 645
 646         <DD>Print a PostScript test page.</DD>
 647
 648 </DL>
 649
 650 <H3>jobs.cgi</H3>
 651
 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
 657 requested.
 658
 659 <P>The following <CODE>WHICH_JOBS</CODE> values are supported:
 660
 661 <DL>
 662
 663 <DT>completed</DT>
 664
 665         <DD>Show only the completed jobs.</DD>
 666
 667 <DT>not-completed</DT>
 668
 669         <DD>Show only the active jobs.</DD>
 670
 671 </DL>
 672
 673 <P>The following <CODE>OP</CODE> values are supported:
 674
 675 <DL>
 676
 677 <DT>job-cancel</DT>
 678
 679         <DD>Cancels a job.</DD>
 680
 681 <DT>job-hold</DT>
 682
 683         <DD>Holds a job indefinitely.</DD>
 684
 685 <DT>job-release</DT>
 686
 687         <DD>Releases a job for printing.</DD>
 688
 689 <DT>job-restart</DT>
 690
 691         <DD>Restarts a stopped, cancelled, completed, or aborted
 692         print job.</DD>
 693
 694 </DL>
 695
 696 <H3>printers.cgi</H3>
 697
 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
 704 each printer.
 705
 706 <P>The following <CODE>WHICH_JOBS</CODE> values are supported:
 707
 708 <DL>
 709
 710 <DT>completed</DT>
 711
 712         <DD>Show only the completed jobs.</DD>
 713
 714 <DT>not-completed</DT>
 715
 716         <DD>Show only the active jobs.</DD>
 717
 718 </DL>
 719
 720 <P>The following <CODE>OP</CODE> values are supported:
 721
 722 <DL>
 723
 724 <DT>print-test-page</DT>
 725
 726         <DD>Print a PostScript test page.</DD>
 727
 728 </DL>
 729
 730
 731 <EMBED SRC="glossary.shtml">
 732
 733 </BODY>
 734 </HTML>