136 lines
11 KiB
HTML
136 lines
11 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||
<meta name="generator" content="Doxygen 1.8.17"/>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
<title>IRremoteESP8266: Internationalisation (I18N) & Locale Files</title>
|
||
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="jquery.js"></script>
|
||
<script type="text/javascript" src="dynsections.js"></script>
|
||
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="search/searchdata.js"></script>
|
||
<script type="text/javascript" src="search/search.js"></script>
|
||
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
</head>
|
||
<body>
|
||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
<div id="titlearea">
|
||
<table cellspacing="0" cellpadding="0">
|
||
<tbody>
|
||
<tr style="height: 56px;">
|
||
<td id="projectalign" style="padding-left: 0.5em;">
|
||
<div id="projectname">IRremoteESP8266
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<!-- end header part -->
|
||
<!-- Generated by Doxygen 1.8.17 -->
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
||
/* @license-end */
|
||
</script>
|
||
<script type="text/javascript" src="menudata.js"></script>
|
||
<script type="text/javascript" src="menu.js"></script>
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
$(function() {
|
||
initMenu('',true,false,'search.php','Search');
|
||
$(document).ready(function() { init_search(); });
|
||
});
|
||
/* @license-end */</script>
|
||
<div id="main-nav"></div>
|
||
<!-- window showing the filter options -->
|
||
<div id="MSearchSelectWindow"
|
||
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||
</div>
|
||
|
||
<!-- iframe showing the search results (closed by default) -->
|
||
<div id="MSearchResultsWindow">
|
||
<iframe src="javascript:void(0)" frameborder="0"
|
||
name="MSearchResults" id="MSearchResults">
|
||
</iframe>
|
||
</div>
|
||
|
||
</div><!-- top -->
|
||
<div class="PageDoc"><div class="header">
|
||
<div class="headertitle">
|
||
<div class="title">Internationalisation (I18N) & Locale Files </div> </div>
|
||
</div><!--header-->
|
||
<div class="contents">
|
||
<div class="textblock"><p>This directory contains the files used by the library to store the text it uses. If you want to add support for a language, this is the correct place. If you are adding text strings to a routine, you should use the ones here.</p>
|
||
<h1><a class="anchor" id="autotoc_md1"></a>
|
||
Changing the language/locale used by the library.</h1>
|
||
<p>There are several ways to change which locale file is used by the library. Use which ever one suits your needs best. To keep the space used by the library to a minimum, all methods require the change to happen at compile time. There is <em>no</em> runtime option to change locales.</p>
|
||
<h2><a class="anchor" id="autotoc_md2"></a>
|
||
Change <tt>_IR_LOCALE_</tt> in the <tt>src/IRremoteESP8266.h</tt> file.</h2>
|
||
<p>In the <a href="../IRremoteESP8266.h#L57-L59">IRremoteESP8266.h</a> file, find and locate the lines that look like: </p><div class="fragment"><div class="line"> {c++}</div>
|
||
<div class="line">#ifndef _IR_LOCALE_</div>
|
||
<div class="line">#define _IR_LOCALE_ en-AU</div>
|
||
<div class="line">#endif // _IR_LOCALE_</div>
|
||
</div><!-- fragment --><p>Change <code>en-AU</code> to the language & country that best suits your needs. e.g. <code>de-DE</code> for Germany/German.</p>
|
||
<h2><a class="anchor" id="autotoc_md3"></a>
|
||
Use a compile-time build flag.</h2>
|
||
<p>Use the compiler flag: <code>-D_IR_LOCALE_=en-AU</code> when compiling the library. Especially when compiling the <code><a class="el" href="IRtext_8cpp.html">IRtext.cpp</a></code> file. Change <code>en-AU</code> to a value which matches one of the file names in this directory. e.g. <code>de-DE</code> for Germany/German, which will use the <code>de_DE.h</code> file.</p>
|
||
<h2><a class="anchor" id="autotoc_md4"></a>
|
||
Use the appropriate pre-prepared build environment. _(PlatformIO only)_</h2>
|
||
<p>If you examine the <code>platformio.ini</code> file located in the same directory as the example code you may find pre-setup compile environments for the different supported locales. Choose the appropriate one for you language by asking PlatformIO to build or upload using that environment. e.g. See <code>IRrecvDumpV2</code>'s <a href="../../examples/IRrecvDumpV2/platformio.ini">platformio.ini</a></p>
|
||
<h2><a class="anchor" id="autotoc_md5"></a>
|
||
Use a custom <tt>build_flags</tt>. _(PlatformIO only)_</h2>
|
||
<p>Edit the <code>platformio.ini</code> file in the directory containing your example/source code. Either in the default PlatformIO environment (<code>[env]</code>), or in which ever PlatformIO environment you using, change or add the following line: </p><div class="fragment"><div class="line">build_flags = -D_IR_LOCALE_=en-AU ; Or use which ever locale variable you want.</div>
|
||
</div><!-- fragment --><p>Every time you change that line, you should do a <code>pio clean</code> or choose the <code>clean</code> option from the build menu, to ensure a fresh copy of <code>IRtext.o</code> is created.</p>
|
||
<h1><a class="anchor" id="autotoc_md6"></a>
|
||
Adding support for a new locale/language.</h1>
|
||
<p>Only <a href="https://en.wikipedia.org/wiki/ASCII#8-bit_codes">ASCII</a>/<a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a> 8-bit characters are supported. <a href="https://en.wikipedia.org/wiki/Unicode">Unicode</a> is <b>not</b> supported. Unicode may work. It may not. It's just not supported. i.e. If Arduino's <code>Serial.print()</code> can handle it, it will probably work.</p>
|
||
<h2><a class="anchor" id="autotoc_md7"></a>
|
||
Copy/create a new locale file in this directory.</h2>
|
||
<p>Copy <a href="en-AU.h">en-AU.h</a> or which every is a closer fit for your language to <code>xx-YY.h</code> where <code>xx</code> is the <a href="https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes">ISO code</a> for the language. e.g. <code>en</code> is English. <code>de</code> is German etc. and <code>YY</code> is the ISO country code. e.g. <code>AU</code> is Australia. Modify the comments and all <code>LOCALE_EN_AU_H_</code>s in the file to <code>LOCALE_XX_YY_H_</code> for your locale.</p>
|
||
<h2><a class="anchor" id="autotoc_md8"></a>
|
||
Override any <tt>#define</tt> values that reside in <tt>defaults.h</tt></h2>
|
||
<p>Go through the <a href="https://github.com/crankyoldgit/IRremoteESP8266/blob/master/src/locale/defaults.h">defaults.h</a> file, and find any <code>#‍define</code> lines that define a macro starting with <code>D_</code> that has text that needs to change for your locale. Copy or create a corresponding <code>#‍define D_STR_HELLOWORLD "Hello World"</code> in your <code>xx-YY.h</code> file, and translate the text appropriately e.g. <code>#‍define D_STR_HELLOWORLD "Bonjour le monde"</code> (French)</p>
|
||
<p>Any values you <code>#‍define</code> in <code>xx-YY.h</code> will override the corresponding value in the <a href="https://github.com/crankyoldgit/IRremoteESP8266/blob/master/src/locale/defaults.h">defaults.h</a> file.</p>
|
||
<h2><a class="anchor" id="autotoc_md9"></a>
|
||
Supporting a dialect/regional variant of another <em>existing</em> language/locale.</h2>
|
||
<p>Similar to the previous step, if you only need to modify a small subset of the strings used in another locale file, then include the other locale file and then make sure to <code>#‍undef</code> any strings that need to be (re-)changed. See the <a href="https://github.com/crankyoldgit/IRremoteESP8266/blob/master/src/locale/de-CH.h">Swiss-German</a> for an example of how to do this. i.e. It <code>#‍include "locale/de-DE.h"</code>s the German locale, and redefines any strings that are not standard <a href="https://github.com/crankyoldgit/IRremoteESP8266/blob/master/src/locale/de-DE.h">German</a>.</p>
|
||
<h1><a class="anchor" id="autotoc_md10"></a>
|
||
Adding new text strings to the library.</h1>
|
||
<p>If you need to add an entirely new string to the library to support some feature etc. e.g. _"Widget"_. You should first understand how the library tries to do this such that it is easy to support different languages for it.</p>
|
||
<ol type="1">
|
||
<li>Use a constant named <code>kWidgetStr</code> in the appropriate statement in the <code>.cpp</code> file.</li>
|
||
<li>Edit <a href="IRtext.cpp">IRtext.cpp</a>, and add the appropriate line for your new constant. e.g. <div class="fragment"><div class="line"> {c++}</div>
|
||
<div class="line">String kWidgetStr = D_STR_WIDGET;</div>
|
||
</div><!-- fragment --></li>
|
||
</ol>
|
||
<p>The <code>kWidgetStr</code> variable will house the sole copy of the string for the entire library. This limits any duplication. The <code>D_STR_WIDGET</code> macro will be what is targeted by the different language / locales files.</p>
|
||
<ol type="1">
|
||
<li>Edit <a href="https://github.com/crankyoldgit/IRremoteESP8266/blob/master/src/locale/defaults.h">locale/defaults.h</a>, and add the appropriate stanza for your new string. e.g. <div class="fragment"><div class="line"> {c++}</div>
|
||
<div class="line">#ifndef D_STR_WIDGET</div>
|
||
<div class="line">#define D_STR_WIDGET "Turbo"</div>
|
||
<div class="line">#endif // D_STR_WIDGET</div>
|
||
</div><!-- fragment --></li>
|
||
<li>_(Manual)_ Update <a href="https://github.com/crankyoldgit/IRremoteESP8266/blob/master/src/IRtext.h">IRtext.h</a>, and add the appropriate line for your new constant. e.g. <div class="fragment"><div class="line"> {c++}</div>
|
||
<div class="line">extern const String kWidgetStr;</div>
|
||
</div><!-- fragment --></li>
|
||
</ol>
|
||
<p>For any file that <code>#‍include <<a class="el" href="IRtext_8h.html">IRtext.h</a>></code>s this file, it will tell it that the string is stored elsewhere, and to look for it elsewhere at the object linking stage of the build. This is what makes the string be referenced from a central location.</p>
|
||
<ol type="1">
|
||
<li>_(Automatic)_ Run <code>tools/generate_irtext_h.sh</code> to update <a href="https://github.com/crankyoldgit/IRremoteESP8266/blob/master/src/IRtext.h">IRtext.h</a>. In the <a href="https://github.com/crankyoldgit/IRremoteESP8266/blob/master/src/locale/">src/locale</a> directory. Run the <code>../../tools/generate_irtext_h.sh</code> command. It will update the file for you automatically. </li>
|
||
</ol>
|
||
</div></div><!-- contents -->
|
||
</div><!-- PageDoc -->
|
||
<!-- start footer part -->
|
||
<hr class="footer"/><address class="footer"><small>
|
||
Generated by  <a href="http://www.doxygen.org/index.html">
|
||
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
||
</a> 1.8.17
|
||
</small></address>
|
||
</body>
|
||
</html>
|