sintl.1

.\"	$Id$
.\"
.\" Copyright (c) 2014, 2018 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt SINTL 1
.Os
.Sh NAME
.Nm sintl
.Nd simple HTML5 translation
.Sh SYNOPSIS
.Nm sintl
.Op Fl cekq
.Op Fl j Ar xliff
.Op Fl u Ar xliff
.Op Ar html5...
.Sh DESCRIPTION
The
.Nm
utility extracts translatable strings from HTML5 files
.Pq Fl e ,
joins XLIFF translation files and untranslated HTML5 files
.Pq Fl j ,
and merges new or removed translations
.Pq Fl u .
Its arguments are as follows:
.Bl -tag -width -Ds
.It Fl c
Copy mode: when used with
.Fl e ,
assigns the same target as the source.
With
.Fl u ,
does the same for new entries.
By default, in either case the target is left blank.
For
.Fl j ,
missing translations are filled in from the input file's content.
.It Fl e
Extracts translatable strings from
.Ar html5 ,
emitting a skeleton XLIFF translation file on standard output.
.It Fl j Ar xliff
Translate
.Pq Qq join
.Ar html5
using
.Ar xliff ,
emitting translated HTML5 on standard output.
.It Fl k
When used with
.Fl u ,
keep entries that are no longer valid.
Otherwise is ignored.
.It Fl q
Quiet: don't note additions and deletions when
.Fl u
is used.
.It Fl u Ar xliff
Update
.Ar xliff
with new translatable strings in
.Ar html5 .
Non-matching terms are discarded unless
.Fl k
is specified.
Additions and deletions are noted on standard error.
.It Ar html5
HTML5 input files to be translated or mined for translatable information.
.El
.Pp
By default,
.Nm
behaves as if
.Fl e
were used.
.Ss Elements and text
Each text node in the HTML5 input files is its own translatable string,
unless the text node is in a phrasing content element.
.Po
Except
.Li <iframe> ,
.Li <noscript> ,
.Li <select> ,
.Li <script> ,
and
.Li <textarea> .
.Pc
For example,
.Bd -literal
<section>
  <div>foo <i>bar</i> baz</div>
  foobar
</section>
.Ed
.Pp
results in two translatable strings:
.Qq foo <i>bar</i> baz
and
.Qq foobar .
.Pp
Contiguous white-space is collapsed into a single space and empty keys
are ignored.
This is why the text node preceding the
.Li div
is omitted.
You may override the whitespace behaviour with the
.Li xml:space="preserve"
attribute, which affects the current and descendent nodes by not
trimming whitespace at all.
.Pp
Translation may be controlled with the
.Li its:translate
attribute, which is set to either
.Li yes
or
.Li no .
When set to
.Li no ,
descendents of the labelled node are not examined for translatable
content.
When set to
.Li yes ,
the opposite is true.
.Ss Attributes
Attributes are carried over into the translatable keys to differentiate
similar content.
.Pp
In a break from standard usage, translations may change attribute values
simply by changing the attribute content.
For example,
.Bd -literal
<trans-unit id="unit1">
  <source><g id="unit1-1" xhtml:href="foo.html">Hi</g>!</source>
  <target>Le <g id="unit1-1" xhtml:href="foo.fr.html">hi</g> !</target>
</trans-unit>
.Ed
.Pp
In this example, the attribute of the translated element will replace
that of the source.
.Ss Optimisations
.Nm
performs a number of optimisations to prevent superfluous content from
being considered for translation.
First, translation strings consisting only of an empty tag are removed.
For example,
.Bd -literal
<p> <img src="path/to/image.png" /> </p>
.Ed
.Pp
These tags may be surrounded by white-space and arbitrarily nested.
.Pp
Second, tags surrounding text are stripped away.
For example,
.Bd -literal
<p> <a href="a/link.html"><i><strong>Hello.</strong></i></a> </p>
.Ed
.Pp
This will produce only the
.Dq Hello.
for translation.
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Let the following simple file,
.Pa index.xml ,
be used as a template for translating into different languages.
.Bd -literal
<!DOCTYPE html>
<html xmlns:its="http://www.w3.org/2005/11/its">
  <head><title>title</title></head>
  <body><p>hello <img src="foo.jpg" /> world</p></body>
</html>
.Ed
.Pp
We can then create an initial XLIFF file as follows.
.Pp
.D1 sintl -e index.xml > index.en.xliff
.Pp
Now edit the XLIFF file.
.Bd -literal
<xliff version="1.2">
  <file source-language="TODO" target-language="en">
    <body>
      <trans-unit id="unit1">
        <source>title</source>
        <target>Title</target>
      </trans-unit>
      <trans-unit id="2">
        <source>hello <x id="0" xhtml:src="foo.jpg"/> world</source>
        <target>Hello, World!</target>
      </trans-unit>
    </body>
  </file>
</xliff>
.Ed
.Pp
If the
.Li lang
attribute were specified on the input
.Li <html>
root element, it would have been propogated in the
.Li source-language
atttribute.
It defaults to
.Li TODO .
Finally, create a translated output file as follows.
.Pp
.D1 sintl -j index.en.xliff index.xml > index.en.html
.Pp
This can be repeated for as many translation files as necessary.
Many systems will use a baseline translation (e.g., English) as the
template, but I find it easier to translate based on sources that are
identifiers, not content.
.Sh STANDARDS
HTML5 files to translate must be valid XML-form HTML5 documents
annotated with a subset of the W3C ITS v2.0 attributes.
Files holding translation dictionaries must be valid XLIFF 1.2 files.
.Sh AUTHORS
The
.Nm
utility was written by
.An Kristaps Dzonsons ,
.Mt kristaps@bsd.lv .
.Sh BUGS
.Nm
ignores translation comments within translated phrasing content.
For example:
.Bd -literal
<i>Hello, <span its:translate="no">world</span>.</i>
.Ed
.Pp
In this example, the non-translatable content is simply passed into the
output.
Non-conformant HTML5, with non-phrasing content embedded in phrasing
content, is explicitly disallowed.
For example:
.Bd -literal
<i>Hello, <div its:translate="no">world</div>.</i>
.Ed