Skip to content

C
converse.js
Commit 4b4f50c2 authored by JC Brand's avatar JC Brand
Browse files
Options

Updated documents.

parent 9b9e514e
Hide whitespace changes
Inline Side-by-side
Showing with 239 additions and 14 deletions
docs/html/_sources/index.txt
View file @ 4b4f50c2
......@@ -29,7 +29,7 @@ webchat experience and that you have control over the data. The latter being a
requirement for many sites dealing with sensitive information.
You'll need to set up your own XMPP server and in order to have
`Session support`_ (i.e. single-signon functionality whereby users are authenticated once and stay
`Session Support`_ (i.e. single-signon functionality whereby users are authenticated once and stay
logged in to XMPP upon page reload) you will also have to add some server-side
code.
......@@ -47,7 +47,7 @@ An XMPP/Jabber server
to connect to an XMPP/Jabber server (Jabber is really just a synonym for XMPP).
You can connect to public XMPP servers like ``jabber.org`` but if you want to
have `Session support`_ you'll have to set up your own XMPP server.
have `Session Support`_ you'll have to set up your own XMPP server.
You can find a list of public XMPP servers/providers on `xmpp.net`_ and a list of
servers that you can set up yourself on `xmpp.org`_.
......@@ -99,7 +99,7 @@ website. This will remove the need for any cross-domain XHR support.
Server-side authentication
==========================
Session support
Session Support
---------------
It's possible to enable single-site login, whereby users already
......@@ -140,7 +140,7 @@ You'll most likely want to implement some kind of single-signon solution for
your website, where users authenticate once in your website and then stay
logged into their XMPP session upon page reload.
For more info on this, read `Session support`_.
For more info on this, read `Session Support`_.
You might also want to have more fine-grained control of what gets included in
the minified Javascript file. Read `Configuration`_ and `Minification`_ for more info on how to do
......@@ -260,8 +260,6 @@ There are two ways to add users.
This setting enables the second mechanism, otherwise by default the first will
be used.
============
Minification
============
......@@ -302,6 +300,91 @@ CSS can be minimized with Yahoo's yuicompressor tool:
yui-compressor --type=css converse.css -o converse.min.css
============
Translations
============
The gettext POT file located in ./locales/converse.pot is the template
containing all translations and from which for each language an individual PO
file is generated.
The POT file contains all translateable strings extracted from converse.js.
To make a user facing string translateable, wrap it in the double underscore helper
function like so:
::
__('This string will be translated at runtime');
After adding the string, you'll need to regenerate the POT file, like so:
::
make pot
You can then create or update the PO file for a specific language by doing the following:
::
msgmerge ./locales/af/LC_MESSAGES/converse.po ./locales/converse.pot -U
This PO file is then what gets translated.
If you've created a new PO file, please make sure to add the following
attributes at the top of the file (under *Content-Transfer-Encoding*). They are
required as configuration settings for Jed, the Javascript translations library
that we're using.
::
"domain: converse\n"
"lang: af\n",
"plural_forms: nplurals=2; plural=(n != 1);\n"
Unfortunately Jed cannot use the PO files directly. We have to generate from it
a file in JSON format and then put that in a .js file for the specific
language.
To generate JSON from a PO file, you'll need po2json for node.js. Run the
following command to install it (npm being the node.js package manager):
::
npm install po2json
You can then convert the translations into JSON format:
::
po2json locales/af/LC_MESSAGES/converse.po locales/af/LC_MESSAGES/converse.json
Now from converse.json paste the data as a value for the "locale_data" key in the
object in the language's .js file.
So, if you are for example translating into German (language code 'de'), you'll
create or update the file ./locale/LC_MESSAGES/de.js with the following code:
::
(function (root, factory) {
define("af", ['jed'], function () {
return factory(new Jed({
"domain": "converse",
"locale_data": {
// Paste the JSON data from converse.json here
}
})
}
}(this, function (i18n) {
return i18n;
}));
making sure to also paste the JSON data as value to the "locale_data" key.
Congratulations, you've now succesfully added your translations. Sorry for all
those hoops you had to jump through.
.. _`conversejs.org`: http://conversejs.org
......
docs/html/index.html
View file @ 4b4f50c2
......@@ -73,7 +73,7 @@
</ul>
</li>
<li><a class="reference internal" href="#server-side-authentication" id="id6">Server-side authentication</a><ul>
<li><a class="reference internal" href="#session-support" id="id7">Session support</a></li>
<li><a class="reference internal" href="#session-support" id="id7">Session Support</a></li>
</ul>
</li>
</ul>
......@@ -98,6 +98,7 @@
<li><a class="reference internal" href="#minifying-css" id="id21">Minifying CSS</a></li>
</ul>
</li>
<li><a class="reference internal" href="#translations" id="id22">Translations</a></li>
</ul>
</div>
<div class="section" id="introduction">
......@@ -113,7 +114,7 @@ properly configure and integrate it into your site.</p>
webchat experience and that you have control over the data. The latter being a
requirement for many sites dealing with sensitive information.</p>
<p>You&#8217;ll need to set up your own XMPP server and in order to have
<a class="reference internal" href="#session-support">Session support</a> (i.e. single-signon functionality whereby users are authenticated once and stay
<a class="reference internal" href="#session-support">Session Support</a> (i.e. single-signon functionality whereby users are authenticated once and stay
logged in to XMPP upon page reload) you will also have to add some server-side
code.</p>
<p>The <a class="reference internal" href="#what-you-will-need">What you will need</a> section has more information on all these
......@@ -126,7 +127,7 @@ requirements.</p>
<p><em>Converse.js</em> implements <a class="reference external" href="https://en.wikipedia.org/wiki/Xmpp">XMPP</a> as its messaging protocol, and therefore needs
to connect to an XMPP/Jabber server (Jabber is really just a synonym for XMPP).</p>
<p>You can connect to public XMPP servers like <tt class="docutils literal"><span class="pre">jabber.org</span></tt> but if you want to
have <a class="reference internal" href="#session-support">Session support</a> you&#8217;ll have to set up your own XMPP server.</p>
have <a class="reference internal" href="#session-support">Session Support</a> you&#8217;ll have to set up your own XMPP server.</p>
<p>You can find a list of public XMPP servers/providers on <a class="reference external" href="http://xmpp.net">xmpp.net</a> and a list of
servers that you can set up yourself on <a class="reference external" href="http://xmpp.org/xmpp-software/servers/">xmpp.org</a>.</p>
</div>
......@@ -166,7 +167,7 @@ website. This will remove the need for any cross-domain XHR support.</p>
<div class="section" id="server-side-authentication">
<h2><a class="toc-backref" href="#id6">Server-side authentication</a><a class="headerlink" href="#server-side-authentication" title="Permalink to this headline"></a></h2>
<div class="section" id="session-support">
<h3><a class="toc-backref" href="#id7">Session support</a><a class="headerlink" href="#session-support" title="Permalink to this headline"></a></h3>
<h3><a class="toc-backref" href="#id7">Session Support</a><a class="headerlink" href="#session-support" title="Permalink to this headline"></a></h3>
<p>It&#8217;s possible to enable single-site login, whereby users already
authenticated in your website will also automatically be logged in on the chat server,
but this will require custom code on your server.</p>
......@@ -196,7 +197,7 @@ practical.</p>
<p>You&#8217;ll most likely want to implement some kind of single-signon solution for
your website, where users authenticate once in your website and then stay
logged into their XMPP session upon page reload.</p>
<p>For more info on this, read <a class="reference internal" href="#session-support">Session support</a>.</p>
<p>For more info on this, read <a class="reference internal" href="#session-support">Session Support</a>.</p>
<p>You might also want to have more fine-grained control of what gets included in
the minified Javascript file. Read <a class="reference internal" href="#configuration">Configuration</a> and <a class="reference internal" href="#minification">Minification</a> for more info on how to do
that.</p>
......@@ -311,6 +312,64 @@ manager, NPM.</p>
<div class="highlight-python"><pre>yui-compressor --type=css converse.css -o converse.min.css</pre>
</div>
</div>
</div>
<div class="section" id="translations">
<h1><a class="toc-backref" href="#id22">Translations</a><a class="headerlink" href="#translations" title="Permalink to this headline"></a></h1>
<p>The gettext POT file located in ./locales/converse.pot is the template
containing all translations and from which for each language an individual PO
file is generated.</p>
<p>The POT file contains all translateable strings extracted from converse.js.</p>
<p>To make a user facing string translateable, wrap it in the double underscore helper
function like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">__</span><span class="p">(</span><span class="s">&#39;This string will be translated at runtime&#39;</span><span class="p">);</span>
</pre></div>
</div>
<p>After adding the string, you&#8217;ll need to regenerate the POT file, like so:</p>
<div class="highlight-python"><pre>make pot</pre>
</div>
<p>You can then create or update the PO file for a specific language by doing the following:</p>
<div class="highlight-python"><pre>msgmerge ./locales/af/LC_MESSAGES/converse.po ./locales/converse.pot -U</pre>
</div>
<p>This PO file is then what gets translated.</p>
<p>If you&#8217;ve created a new PO file, please make sure to add the following
attributes at the top of the file (under <em>Content-Transfer-Encoding</em>). They are
required as configuration settings for Jed, the Javascript translations library
that we&#8217;re using.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="s">&quot;domain: converse</span><span class="se">\n</span><span class="s">&quot;</span>
<span class="s">&quot;lang: af</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span>
<span class="s">&quot;plural_forms: nplurals=2; plural=(n != 1);</span><span class="se">\n</span><span class="s">&quot;</span>
</pre></div>
</div>
<p>Unfortunately Jed cannot use the PO files directly. We have to generate from it
a file in JSON format and then put that in a .js file for the specific
language.</p>
<p>To generate JSON from a PO file, you&#8217;ll need po2json for node.js. Run the
following command to install it (npm being the node.js package manager):</p>
<div class="highlight-python"><pre>npm install po2json</pre>
</div>
<p>You can then convert the translations into JSON format:</p>
<div class="highlight-python"><pre>po2json locales/af/LC_MESSAGES/converse.po locales/af/LC_MESSAGES/converse.json</pre>
</div>
<p>Now from converse.json paste the data as a value for the &#8220;locale_data&#8221; key in the
object in the language&#8217;s .js file.</p>
<p>So, if you are for example translating into German (language code &#8216;de&#8217;), you&#8217;ll
create or update the file ./locale/LC_MESSAGES/de.js with the following code:</p>
<div class="highlight-python"><pre>(function (root, factory) {
define("af", ['jed'], function () {
return factory(new Jed({
"domain": "converse",
"locale_data": {
// Paste the JSON data from converse.json here
}
})
}
}(this, function (i18n) {
return i18n;
}));</pre>
</div>
<p>making sure to also paste the JSON data as value to the &#8220;locale_data&#8221; key.</p>
<p>Congratulations, you&#8217;ve now succesfully added your translations. Sorry for all
those hoops you had to jump through.</p>
</div>
......
docs/html/searchindex.js
View file @ 4b4f50c2
Search.setIndex({objects:{},terms:{all:0,code:0,partial:0,queri:0,webchat:0,middl:0,depend:0,sensit:0,under:0,fals:0,mechan:0,jack:0,veri:0,list:0,pleas:0,prevent:0,second:0,pass:0,download:0,further:0,fullnam:0,even:0,index:0,what:0,hide:0,section:0,current:0,version:0,"new":0,net:0,method:0,here:0,box:0,great:0,convers:0,mysit:0,implement:0,via:0,extra:0,solut:0,href:0,auto_list_room:0,instal:0,zip:0,commun:0,two:0,websit:0,stylesheet:0,call:0,recommend:0,type:0,until:0,tightli:0,more:0,yahoo:0,must:0,room:0,setup:[],xhr:0,can:0,purpos:0,fetch:0,control:0,quickstart:0,share:0,tag:0,proprietari:0,explor:0,occup:0,end:0,goal:0,snippet:0,how:0,sid:0,instead:0,css:0,npm:0,regener:0,product:0,resourc:0,after:0,usabl:0,befor:0,data:0,demonstr:0,man:0,practic:0,bind:0,django:0,inform:0,order:0,xmpp:0,over:0,streamlin:0,write:0,jid:0,fit:0,pend:0,therefor:0,might:0,them:0,anim:0,"return":0,thei:0,initi:0,front:0,now:0,introduct:0,name:0,authent:0,ejabberd:0,each:0,side:0,mean:0,domain:0,realli:0,legwork:0,connect:0,variabl:0,open:0,content:0,rel:0,internet:0,proxi:0,insid:0,standard:0,standalon:0,releas:0,org:0,blogpost:0,keep:0,yui:0,first:0,origin:0,softwar:0,render:0,onc:0,lastnam:0,number:0,yourself:0,restrict:0,alreadi:0,owner:0,jabber:0,differ:0,script:0,messag:0,attach:0,attack:0,luckili:0,option:0,tool:0,specifi:0,compressor:0,part:0,exactli:0,than:0,serv:0,kind:0,provid:0,remov:0,bridg:0,toward:[],browser:0,sai:0,saa:0,modern:0,ani:0,packag:0,have:0,tabl:0,need:0,moffitt:0,bosh_service_url:0,prebind:0,min:0,latter:0,also:0,exampl:0,build:0,which:0,singl:0,sure:0,though:0,track:0,object:0,most:0,deploi:0,homepag:0,don:0,url:0,request:0,xdomainrequest:0,show:0,text:0,session:0,fine:0,find:0,onli:0,locat:0,firstnam:0,configur:0,apach:0,should:0,folder:0,meant:0,get:0,opkod:0,requir:0,enabl:0,"public":0,reload:0,integr:0,where:0,set:0,stroph:0,see:0,close:0,state:0,between:0,experi:0,hide_muc_serv:0,screen:0,javascript:0,job:0,bosh:0,cor:0,instant:0,shortliv:0,conversej:0,etc:0,grain:0,mani:0,login:0,com:0,load:0,backend:0,onconnect:0,json:0,much:0,besid:0,subscrib:0,minifi:0,togeth:0,present:0,multi:0,servic:0,plugin:0,chat:0,demo:0,auto_subscrib:0,site:0,rid:0,minim:0,media:0,make:0,minif:0,cross:0,same:0,html:0,signon:0,http:0,webserv:0,optim:0,upon:0,hand:0,user:0,xhr_user_search:0,recent:0,stateless:0,person:[],contact:0,wherebi:0,thi:0,choos:0,usual:0,protocol:0,just:0,web:0,xmlhttprequest:0,add:0,other:0,input:0,yuicompressor:0,match:0,applic:0,read:0,nginx:0,traffic:0,like:0,xss:0,success:0,specif:0,server:0,benefit:0,either:0,page:0,deal:0,some:0,back:0,deploy:0,overcom:0,refer:0,run:0,host:0,panel:0,src:0,about:0,controlbox:0,manag:0,act:0,own:0,automat:0,your:0,log:0,wai:0,support:0,custom:0,avail:0,start:[],includ:0,lot:0,suit:0,"function":0,properli:0,form:0,bundl:0,link:0,synonym:0,"true":0,longer:0,info:0,made:0,possibl:0,"default":0,below:0,otherwis:0,problem:0,expect:0,featur:0,creat:0,exist:0,file:0,want:0,when:0,detail:0,field:0,valid:0,test:0,you:0,nice:0,node:0,stai:0,requirej:0},objtypes:{},titles:["Introduction"],objnames:{},filenames:["index"]})
\ No newline at end of file
Search.setIndex({objects:{},terms:{all:0,code:0,partial:0,queri:0,webchat:0,follow:0,middl:0,depend:0,sensit:0,sorri:0,those:0,under:0,string:0,fals:0,mechan:0,jack:0,veri:0,list:0,pleas:0,prevent:0,past:0,second:0,pass:0,download:0,further:0,fullnam:0,even:0,index:0,what:0,hide:0,section:0,current:0,version:0,"new":0,net:0,"public":0,gener:0,here:0,valu:0,box:0,convert:0,convers:0,mysit:0,implement:0,via:0,extra:0,apach:0,releas:0,href:0,org:0,auto_list_room:0,instal:0,from:0,zip:0,commun:0,doubl:0,two:0,websit:0,stylesheet:0,call:0,recommend:0,type:0,until:0,tightli:0,more:0,yahoo:0,must:0,room:0,setup:[],xhr:0,can:0,lc_messag:0,purpos:0,root:0,fetch:0,control:0,quickstart:0,share:0,templat:0,tag:0,proprietari:0,explor:0,occup:0,end:0,goal:0,write:0,how:0,sid:0,instead:0,css:0,updat:0,npm:0,regener:0,product:0,resourc:0,after:0,usabl:0,befor:0,underscor:0,data:0,demonstr:0,man:0,practic:0,bind:0,django:0,inform:0,order:0,xmpp:0,over:0,through:0,streamlin:0,snippet:0,jid:0,directli:0,fit:0,pend:0,therefor:0,might:0,them:0,anim:0,"return":0,thei:0,initi:0,front:0,now:0,introduct:0,name:0,authent:0,ejabberd:0,each:0,side:0,mean:0,domain:0,individu:0,realli:0,legwork:0,connect:0,extract:0,variabl:0,open:0,content:0,rel:0,internet:0,plural:0,factori:0,po2json:0,proxi:0,insid:0,standard:0,standalon:0,put:0,succesfulli:0,blogpost:0,keep:0,yui:0,first:0,origin:0,softwar:0,render:0,onc:0,hoop:0,lastnam:0,number:0,yourself:0,restrict:0,alreadi:0,owner:0,jabber:0,differ:0,script:0,top:0,messag:0,attach:0,attack:0,jed:0,luckili:0,option:0,tool:0,specifi:0,compressor:0,part:0,exactli:0,than:0,serv:0,jump:0,kind:0,provid:0,remov:0,bridg:0,toward:[],browser:0,sai:0,saa:0,modern:0,ani:0,packag:0,have:0,tabl:0,need:0,moffitt:0,bosh_service_url:0,prebind:0,min:0,latter:0,also:0,exampl:0,build:0,which:0,singl:0,sure:0,though:0,track:0,object:0,most:0,deploi:0,homepag:0,don:0,url:0,request:0,face:0,runtim:0,xdomainrequest:0,show:0,german:0,text:0,session:0,fine:0,find:0,onli:0,locat:0,just:0,configur:0,solut:0,should:0,folder:0,local:0,meant:0,get:0,opkod:0,cannot:0,requir:0,enabl:0,method:0,reload:0,integr:0,contain:0,where:0,set:0,stroph:0,see:0,close:0,state:0,between:0,experi:0,hide_muc_serv:0,attribut:0,kei:0,screen:0,javascript:0,job:0,bosh:0,cor:0,instant:0,shortliv:0,conversej:0,etc:0,grain:0,mani:0,login:0,com:0,load:0,pot:0,backend:0,creat:0,json:0,much:0,besid:0,subscrib:0,msgmerg:0,great:0,minifi:0,togeth:0,i18n:0,present:0,multi:0,servic:0,plugin:0,defin:0,file:0,helper:0,demo:0,auto_subscrib:0,site:0,rid:0,minim:0,media:0,make:0,minif:0,cross:0,same:0,html:0,signon:0,http:0,webserv:0,optim:0,upon:0,hand:0,user:0,xhr_user_search:0,recent:0,stateless:0,person:[],contact:0,command:0,wherebi:0,thi:0,choos:0,usual:0,plural_form:0,protocol:0,firstnam:0,languag:0,web:0,xmlhttprequest:0,had:0,add:0,valid:0,input:0,yuicompressor:0,match:0,applic:0,format:0,read:0,nginx:0,traffic:0,like:0,xss:0,success:0,specif:0,server:0,benefit:0,either:0,page:0,deal:0,nplural:0,some:0,back:0,librari:0,deploy:0,overcom:0,refer:0,run:0,host:0,panel:0,src:0,about:0,controlbox:0,unfortun:0,act:0,own:0,encod:0,automat:0,wrap:0,your:0,manag:0,log:0,wai:0,transfer:0,support:0,custom:0,avail:0,start:[],includ:0,lot:0,suit:0,"function":0,properli:0,form:0,bundl:0,link:0,translat:0,synonym:0,"true":0,congratul:0,requirej:0,info:0,made:0,locale_data:0,possibl:0,"default":0,below:0,otherwis:0,problem:0,expect:0,featur:0,onconnect:0,exist:0,chat:0,want:0,when:0,detail:0,gettext:0,field:0,other:0,test:0,you:0,nice:0,node:0,stai:0,lang:0,longer:0},objtypes:{},titles:["Introduction"],objnames:{},filenames:["index"]})
\ No newline at end of file
docs/source/index.rst
View file @ 4b4f50c2
......@@ -260,8 +260,6 @@ There are two ways to add users.
This setting enables the second mechanism, otherwise by default the first will
be used.
============
Minification
============
......@@ -302,6 +300,91 @@ CSS can be minimized with Yahoo's yuicompressor tool:
yui-compressor --type=css converse.css -o converse.min.css
============
Translations
============
The gettext POT file located in ./locales/converse.pot is the template
containing all translations and from which for each language an individual PO
file is generated.
The POT file contains all translateable strings extracted from converse.js.
To make a user facing string translateable, wrap it in the double underscore helper
function like so:
::
__('This string will be translated at runtime');
After adding the string, you'll need to regenerate the POT file, like so:
::
make pot
You can then create or update the PO file for a specific language by doing the following:
::
msgmerge ./locales/af/LC_MESSAGES/converse.po ./locales/converse.pot -U
This PO file is then what gets translated.
If you've created a new PO file, please make sure to add the following
attributes at the top of the file (under *Content-Transfer-Encoding*). They are
required as configuration settings for Jed, the Javascript translations library
that we're using.
::
"domain: converse\n"
"lang: af\n"
"plural_forms: nplurals=2; plural=(n != 1);\n"
Unfortunately Jed cannot use the PO files directly. We have to generate from it
a file in JSON format and then put that in a .js file for the specific
language.
To generate JSON from a PO file, you'll need po2json for node.js. Run the
following command to install it (npm being the node.js package manager):
::
npm install po2json
You can then convert the translations into JSON format:
::
po2json locales/af/LC_MESSAGES/converse.po locales/af/LC_MESSAGES/converse.json
Now from converse.json paste the data as a value for the "locale_data" key in the
object in the language's .js file.
So, if you are for example translating into German (language code 'de'), you'll
create or update the file ./locale/LC_MESSAGES/de.js with the following code:
::
(function (root, factory) {
define("af", ['jed'], function () {
return factory(new Jed({
"domain": "converse",
"locale_data": {
// Paste the JSON data from converse.json here
}
})
}
}(this, function (i18n) {
return i18n;
}));
making sure to also paste the JSON data as value to the "locale_data" key.
Congratulations, you've now succesfully added your translations. Sorry for all
those hoops you had to jump through.
.. _`conversejs.org`: http://conversejs.org
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7