mirror of
https://github.com/ganelson/inform.git
synced 2024-07-16 14:04:24 +03:00
263 lines
15 KiB
HTML
263 lines
15 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>A Guide to Language Bundles</title>
|
|
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
|
|
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
|
|
</head>
|
|
<body class="commentary-font">
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-assets/Inform.png" height=72">
|
|
</a></h1>
|
|
<ul><li><a href="../index.html">home</a></li>
|
|
</ul><h2>Compiler</h2><ul>
|
|
<li><a href="../structure.html">structure</a></li>
|
|
<li><a href="../inbuildn.html">inbuild</a></li>
|
|
<li><a href="../inform7n.html">inform7</a></li>
|
|
<li><a href="../intern.html">inter</a></li>
|
|
<li><a href="../services.html">services</a></li>
|
|
<li><a href="../secrets.html">secrets</a></li>
|
|
</ul><h2>Other Tools</h2><ul>
|
|
<li><a href="../inblorbn.html">inblorb</a></li>
|
|
<li><a href="../indocn.html">indoc</a></li>
|
|
<li><a href="../inform6.html">inform6</a></li>
|
|
<li><a href="../inpolicyn.html">inpolicy</a></li>
|
|
<li><a href="../inrtpsn.html">inrtps</a></li>
|
|
</ul><h2>Resources</h2><ul>
|
|
<li><a href="../extensions.html">extensions</a></li>
|
|
<li><a href="../kits.html">kits</a></li>
|
|
</ul><h2>Repository</h2><ul>
|
|
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=18> github</a></li>
|
|
</ul><h2>Related Projects</h2><ul>
|
|
<li><a href="../../../inweb/index.html">inweb</a></li>
|
|
<li><a href="../../../intest/index.html">intest</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
<!--Weave of 'A Guide to Language Bundles' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inbuild</a></li><li><a href="index.html#M">Manual</a></li><li><b>A Guide to Language Bundles</b></li></ul></div>
|
|
<p class="purpose">Provisional documentation on language bundles.</p>
|
|
|
|
<ul class="toc"><li><a href="M-agtlb.html#SP1">§1. About languages</a></li><li><a href="M-agtlb.html#SP3">§3. Language bundles</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. About languages. </b>Like a "kit" or an "extension", a "language bundle" is a resource which Inbuild
|
|
can use. Language here means the human kind: English, French, Spanish and so on.
|
|
</p>
|
|
|
|
<p class="commentary">For each Inform project it looks at, Inbuild must determine:
|
|
</p>
|
|
|
|
<ul class="items"><li>● The "language of play" (LOP), which is the language printed by the story and
|
|
recognised in commands by the player.
|
|
</li><li>● The "language of syntax" (LOS), which is the language the source text for the
|
|
story is written in.
|
|
</li></ul>
|
|
<p class="commentary">Both are by default English. If the LOS is anything other than English, then the LOP
|
|
must be the same as the LOS. But English syntax has often been used to write
|
|
Inform stories with LOP other than English, and indeed this is the usual way to
|
|
write non-English stories. (It is an arduous process to make Inform work
|
|
with an LOS other than English, and the tool chain needs improvement in this
|
|
area. But Inbuild understands the necessary concepts, at least.)
|
|
</p>
|
|
|
|
<p class="commentary">The LOP is recorded on the Library Card index entry for an Inform project,
|
|
and is also included in the iFiction record of a released story.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. </b>Inbuild recognises the language of play by looking at the opening, or
|
|
"bibliographic", sentence of an Inform project. For many projects this
|
|
consists of a title and perhaps an author, like so:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>"Why Didn't They Ask Evans?" by Agatha Christie</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">But it can optionally add a bracketed note giving the language:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>"Le Port des brumes" by Georges Simenon (in French)</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">This bracketed note can take two forms. If it begins "in", then the rest must
|
|
be the English form of the name of a language — in this instance, "French".
|
|
This must be a language for which Inbuild can find a language bundle (see below).
|
|
The LOP will be French, and the LOS will be English.
|
|
</p>
|
|
|
|
<p class="commentary">If the note does not begin "in", then it must be text recognised by a language
|
|
bundle visible to Inbuild (see below). For example:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>"Le Port des brumes" by Georges Simenon (en français)</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">This time the LOP and LOS are both French. Inbuild was able to determine that
|
|
because the French language bundle picked up on the phrase "en français", which
|
|
Inbuild itself does not recognise.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. Language bundles. </b>Inform can only compile a project whose LOP is other than English if it is
|
|
given extra resources to do so: the default installation covers only English.
|
|
In a typical situation, three resources are needed:
|
|
</p>
|
|
|
|
<ul class="items"><li>● A language bundle, such as "French".
|
|
</li><li>● A kit of Inter code, such as "FrenchLanguageKit".
|
|
</li><li>● An extension of Inform 7 source text, such as "French Language by Paul Mensonge".
|
|
</li></ul>
|
|
<p class="commentary">Note: In fact at present the Inform installation does ship with language bundles
|
|
for English, French, German, Italian, Spanish and Swedish, but those other than
|
|
English are likely to be dropped from the core installation in a future release,
|
|
and we recommend that groups of translators begin to keep their own copies,
|
|
distributing those alongside the necessary kit and extension.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. </b>Language bundles should be stored in a subdirectory called "Languages",
|
|
either of an individual project's Materials directory (in which case they will
|
|
be visible just to that project) or in a so-called "nest" of resources. Language
|
|
bundles shipped in the core Inform distribution are at <span class="extract"><span class="extract-syntax">inform7/Internal/Languages</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">Each language bundle is itself a directory, whose name must be the English name
|
|
of the language (for example, <span class="extract"><span class="extract-syntax">French</span></span>). In v9 (and early betas of v10) of Inform,
|
|
this directory then contained a file of metadata called <span class="extract"><span class="extract-syntax">about.txt</span></span>. This file
|
|
is now forbidden to exist, and instead there must be a file called <span class="extract"><span class="extract-syntax">language_metadata.json</span></span>.
|
|
This is a JSON file very similar to the ones used for kit metadata: see <a href="M-agtk.html" class="internal">A Guide to Kits</a>,
|
|
which it is probably helpful to read before going much further with this.
|
|
</p>
|
|
|
|
<p class="commentary">For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">{</span>
|
|
<span class="plain-syntax"> "is": {</span>
|
|
<span class="plain-syntax"> "type": "language",</span>
|
|
<span class="plain-syntax"> "title": "French"</span>
|
|
<span class="plain-syntax"> },</span>
|
|
<span class="plain-syntax"> "needs": [ {</span>
|
|
<span class="plain-syntax"> "need": {</span>
|
|
<span class="plain-syntax"> "type": "kit",</span>
|
|
<span class="plain-syntax"> "title": "FrenchLanguageKit"</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> } ],</span>
|
|
<span class="plain-syntax"> "language-details": {</span>
|
|
<span class="plain-syntax"> "translated-name": "Français",</span>
|
|
<span class="plain-syntax"> "iso-639-1-code": "fr",</span>
|
|
<span class="plain-syntax"> "translated-syntax-cue": "en français"</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax">}</span>
|
|
</pre>
|
|
<p class="commentary">Note that at present language bundles have no authorship, so that the <span class="extract"><span class="extract-syntax">"is"</span></span>
|
|
object does not give an <span class="extract"><span class="extract-syntax">"author"</span></span> field. (This may change in later builds.)
|
|
Language bundles can have version numbers, like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> "is": {</span>
|
|
<span class="plain-syntax"> "type": "language",</span>
|
|
<span class="plain-syntax"> "title": "French",</span>
|
|
<span class="plain-syntax"> "version": "2.3.17"</span>
|
|
<span class="plain-syntax"> },</span>
|
|
</pre>
|
|
<p class="commentary">But the English language kit shipped with Inform is not version-numbered.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. </b>A language bundle can only have unconditional "needs", each of which must
|
|
be a kit, and there always has to be at least one kit. If at all possible,
|
|
use exactly one kit, and give it a name in the form <span class="extract"><span class="extract-syntax">WhateverLanguageKit</span></span>,
|
|
where <span class="extract"><span class="extract-syntax">Whatever</span></span> is the English form of the language's name. Thus
|
|
<span class="extract"><span class="extract-syntax">SpanishLanguageKit</span></span>, not <span class="extract"><span class="extract-syntax">EspanolLanguageKit</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">The kits listed by a language bundle are automatically included by Inbuild
|
|
when compiling a project whose LOP is that language.
|
|
</p>
|
|
|
|
<p class="commentary">Note that a language bundle does not have an extension among its "needs". It
|
|
would be incorrect to write:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> "needs": [ {</span>
|
|
<span class="plain-syntax"> "need": {</span>
|
|
<span class="plain-syntax"> "type": "kit",</span>
|
|
<span class="plain-syntax"> "title": "FrenchLanguageKit"</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> }, {</span>
|
|
<span class="plain-syntax"> "need": {</span>
|
|
<span class="plain-syntax"> "type": "extension",</span>
|
|
<span class="plain-syntax"> "title": "French Language",</span>
|
|
<span class="plain-syntax"> "author": "Paul Mensonge"</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> } ],</span>
|
|
</pre>
|
|
<p class="commentary">Although the extension is indeed necessary, it should be given in the "needs"
|
|
of the kit <span class="extract"><span class="extract-syntax">FrenchLanguageKit</span></span>, not of the language bundle "French". Thus
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">French --- needs --> FrenchLanguageKit --- needs --> French Language by Paul Mensonge</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. </b>The <span class="extract"><span class="extract-syntax">language-details.translated-name</span></span> field is required, and should the the
|
|
language as it is normally written in the language itself: thus, <span class="extract"><span class="extract-syntax">Deutsch</span></span> not
|
|
<span class="extract"><span class="extract-syntax">German</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">As its name suggests, the <span class="extract"><span class="extract-syntax">language-details.iso-639-1-code</span></span> field should be
|
|
a valid ISO 639-1 code for the language in question — a two-letter code such
|
|
as "de" (German) or "hr" (Croatian). See for example
|
|
<a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external">Wikipedia</a> for a complete list.
|
|
</p>
|
|
|
|
<p class="commentary">The field <span class="extract"><span class="extract-syntax">language-details.translated-syntax-cue</span></span> is optional. If given, it's
|
|
a "cue" to say that the LOS is this language: see above. For example, it might
|
|
be <span class="extract"><span class="extract-syntax">en français</span></span>. Note however than this cue text must not start with the word
|
|
<span class="extract"><span class="extract-syntax">in</span></span>, as that would lead to ambiguity about whether the LOP or the LOS is being
|
|
set. So, for example, <span class="extract"><span class="extract-syntax">scritto in italiano</span></span> not <span class="extract"><span class="extract-syntax">in italiano</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">If the user tries to build a project "scritto in italiano", then Inbuild will
|
|
read a file of Preform declarations called <span class="extract"><span class="extract-syntax">Syntax.preform</span></span> inside the bundle:
|
|
in this example, at <span class="extract"><span class="extract-syntax">Italian/Syntax.preform</span></span>. Should such a file not exist (or
|
|
not declare any nonterminals) then Inform will produce a problem like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">Problem. The project says that its syntax is written in a language other than</span>
|
|
<span class="plain-syntax">English (specifically, Italian), but the language bundle for that language does</span>
|
|
<span class="plain-syntax">not provide a file of Preform definitions.</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>§7. </b>Finally, there is a very sketchy ability for a language bundle to localise
|
|
the Index for a project: see e.g. <span class="extract"><span class="extract-syntax">inform7/Internal/Languages/French/Index.txt</span></span>.
|
|
Note that this takes effect only if the user asks it to with a use option:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">Use</span><span class="plain-syntax"> </span><span class="identifier-syntax">French</span><span class="plain-syntax"> </span><span class="identifier-syntax">language</span><span class="plain-syntax"> </span><span class="identifier-syntax">index</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="M-agtk.html">❮</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-ui.html">ui</a></li><li class="progresssection"><a href="M-agtk.html">agtk</a></li><li class="progresscurrent">agtlb</li><li class="progresssection"><a href="M-agtpm.html">agtpm</a></li><li class="progresssection"><a href="M-agtr.html">agtr</a></li><li class="progresssection"><a href="M-rc.html">rc</a></li><li class="progresschapter"><a href="1-mn.html">1</a></li><li class="progressnext"><a href="M-agtpm.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|