Difference between revisions of "Help:Adding a Language"

From Pathfinder Wiki
 
(19 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
<div style="margin-right:3em; float:left;">__TOC__</div>
 +
 
==Introduction==
 
==Introduction==
−
This wiki uses the Translate extension which is described at [[:Help:Translation]]. You should read that first. This page describes some of the things we did to make translation easier.
+
This wiki uses the Translate extension which is described at [[:Help:Translation]]. You should read that first. This page describes some of the things we did to make translation easier.
  
 
==Steps==
 
==Steps==
 
===GetLangSuffix===
 
===GetLangSuffix===
−
The first thing to do when adding a new language to the wiki is to edit [[:Template:GetLangSuffix]]. The template is protected though, so you may need to leave a request in the [[:Pathfinder Wiki:Community portal|Discussion]] page. Administrators patrol this wiki daily, so one of us will see the request soon after you leave it.
+
The first thing to do when adding a new language to the wiki is to edit [[:Template:GetLangSuffix]]. The template is protected though, so you may need to leave a request in the [[:Pathfinder Wiki:Community portal|Discussion]] page. Administrators patrol this wiki daily, so one of us will see the request soon after you leave it.
  
−
The GetLangSuffix template returns text like ''/es'' or ''/de'' depending on where it is invoked from. It basically extracts the last element of the page name, runs it through a #switch statement, and returns a slash plus the language code if it recognizes the last element as a language code. If it is invoked from an English page, or from a page that it doesn't recognize as a translated page, it will return an empty string. Whatever it returns - an empty string, or a language code - can be tacked to the end of any page title to refer to the translated version of that page. This technique is used ''extensively'' throughout the wiki.
+
The GetLangSuffix template returns text like ''/es'' or ''/de'' depending on where it is invoked from. It basically extracts the last element of the page name, runs it through a #switch statement, and returns a slash plus the language code if it recognizes the last element as a language code. If it is invoked from an English page, or from a page that it doesn't recognize as a translated page, it will return an empty string. Whatever it returns - an empty string, or a language code - can be tacked to the end of any page title to refer to the translated version of that page. This technique is used ''extensively'' throughout the wiki.
  
 
===Localization:All===
 
===Localization:All===
−
The next step is to go to the [[:Localization:All]] page, and create a translation for the new language. This page is a list of words and phrases that we use in templates so that we don't have to translate the templates. Templates can be very complex, and they are difficult to get right. Most templates will display text to the user by having that text in the localization page, and then using the [[:Template:Localize]] template which will fetch the translated phrase based on the results returned by <nowiki>{{</nowiki>GetLangSuffix}}. For example:
+
The next step is to go to the [[:Localization:All]] page and create a translation for the new language. This page is a list of words and phrases that we use in templates so that we don't have to translate the templates. Templates can be very complex, and they are difficult to get right. Most templates will display text to the user by having that text in the localization page, and then using the [[:Template:Localize]] template which will fetch the translated phrase based on the results returned by <nowiki>{{</nowiki>GetLangSuffix}}. For example:
  
 
<nowiki>{{</nowiki>Localize|Honor}}
 
<nowiki>{{</nowiki>Localize|Honor}}
Line 16: Line 18:
 
:{{Localize|Honor}}
 
:{{Localize|Honor}}
  
−
Which is admittedly not that impressive - except that if you call if from a page ending in /es, it will return "Especialidad" which is the Spanish translation of the word "Honor". That makes it quite magical. It's important to note that the argument passed to the Localize template be in English, and that it have the correct unit name. Spelling and case are important. What this means is that you should not expect  
+
Which is admittedly not that impressive - except that if you call if from a page ending in /es, it will return "Especialidad" which is the Spanish translation of the word "Honor". That makes it quite magical. It's important to note that the argument passed to the Localize template be in English, and that it have the correct unit name. Spelling and case are important. What this means is that you should not expect  
  
 
<nowiki>{{</nowiki>Localize|Especialidad}}
 
<nowiki>{{</nowiki>Localize|Especialidad}}
  
−
to work. The name of the phrase is "Honor" and it doesn't matter what language you invoke it from.
+
to work. The name of the phrase is "Honor" and it doesn't matter what language you invoke it from.
 +
 
 +
The phrases in [[:Localization:All]] are used to display the names of the tabs, the names of the hierarchical names of the SDA Church organization (i.e., General Conference, North American Division, etc), the honor categories, the names of the Master Awards, and basically, anything we want to display in a template. If a user is going to see it, it should be in [[:Localization:All]].
 +
 
 +
Each entry in [[:Localization:All]] is saved into a table of the database by calling a template. Those templates have two main parameter's. One is the '''id''', that is used to get the translated text with the [[Template:Localize]]. This parameter shouldn't be touched unless you know what you are doing. To find out where a text get's used on the wiki you can use [[Help:Debug Localization|this]] page. The second parameter is '''text''', that is where the translation goes.
 +
 
 +
===Localization:''other pages''===
 +
The {{OpenCurly}}Localize}} template can take an optional second argument to specify an alternate localization page containing the localization (the first argument is the term to localize). This allows us to separate localization terms into more than one page so that the localization replacements can run faster and have a little more organization. The template is called thusly:
 +
 
 +
{{OpenCurly}}Localize|Lorem ipsum|page=''alt_page''}} which would search for term in [[Localization:alt_page]] (which doesn't exist - it's just an example).
 +
 
 +
If the second argument is not specified, the template defaults to using [[Localization:All]]. Here is a list of alternate Localization pages which also need to be translated:
 +
 
 +
* [[Localization:Authorities]]
 +
* [[Localization:Countries]]
 +
* [[Localization:Default Bible version]]
 +
* [[Localization:Honors]]
 +
* [[Localization:HonorTitle]]
 +
* [[Localization:Images]]
 +
* That's all so far. It's a short list, but we expect it to grow.
 +
 
 +
===Translating AY Honors===
 +
When translating the honors, keep in mind there are three tabs (or pages) that need to be worked on for the honor to be "completely" translated. These three tabs include:
 +
* Overview
 +
* Requirements
 +
* Answer Key
 +
It would be easiest to start translating the Requirements tab first, because the other tabs depend on the requirements to generate the info.
 +
 
 +
The best order to start translating honors is to go through those that are connected directly to Investiture Achievement (the classes and curricula used for Pathfinders). These honors are usually more frequently used popular.
 +
 
 +
You can find a list of these honors by clicking this link: [[:Category:AY Honors/IAConnection|IA Connection]]
 +
 
 +
==Language Specific Graphics==
 +
There are some graphics that contain text, so a new localized version of the graphic needs to be created too. [[Localization:Images|Here]] is a list of those graphics and that is also the place to define which graphic is shown for which language.
 +
 
 +
==Choose a default Bible version==
 +
[[:Template:Bible link]] takes a Bible verse as a parameter and converts that to a link to [http://biblegateway.com biblegateway.com]. This template cannot use [[:Localization:All]] to pass in the Bible version because of the additional wiki markup that is added to everything the <nowiki>{{Localize}}</nowiki> template must return. This extra text is ignored by the wiki rendering software, but we need to use it to specify which version of the Bible is to be used, and the text gets added to a URL. URLs don't ignore wiki markup, so this operation fails. So we had to take a different approach.
 +
 
 +
You will need to first figure out what version string [biblegateway.com] needs to query a language-specific Bible translation. In English, this string is NKJV. Once you know what string you need to use, create a file in <nowiki>[[</nowiki>Localization:Default Bible verse/''language code'']]. The only thing that should be placed in the file is the string biblegateway.com needs. Do not use the Translation extension to create this file.
 +
 
 +
==Configure Wikipedia links==
 +
Most wikis support ''interwikis'' - which is an easy way to link to another wiki such as wikipedia. On our wiki, we can link to a wikipedia article by adding <nowiki>[[</nowiki>W:Anax junius]] to an article. It creates a link to the wikipedia article about [[w:Anax junius|Anax junius]]. But it will take you to the ''English'' wikipedia. To make that work in another language, we have to translate [[Template:Localize wikipedia]] and change the ''w'' to something else. In Spanish, the ''w'' becomes ''esw''. It's usually just the language code plus a w. We have several templates that automatically localize to the language of the invoking page, and some of those (such as [[Template:Species id]]) provide a link to the wikipedia article of the species (using its Latin name, so that should work in most languages).
 +
 
 +
==How to add/change a language specific logo==
 +
First of all, the image needs to be created. The images we use here were created by [[User:DesignerThan|DesignerThan]]. Contact him and he will be glad to create the needed image.
 +
 
 +
The created image then needs to be uploaded to the Wiki. Ask any admin for assistance to do this, or to see if DesignerThan has already done it.
 +
 
 +
For the next step, you need the link to the file. You can get that by opening the page of the image and clicking on "Original File". Now you can copy the link.
 +
 
 +
Now you are ready to do the magic. Go to the page [[MediaWiki:Chameleon.css]] and start edit mode. There you copy the code of an existing language and copy-paste it at the bottom of the page. Change the comment so it names the new language; also, change the short language name to whatever you need and exchange the link with the link of your image (only paste the parts needed, so it looks like the others).
 +
 
 +
Now the new logo should be visible if the interface is in that particular language. If it does not appear, try to empty your browser cache and reload the page.
 +
 
 +
If you want to use the same logo for multiple languages, have a look at the [[MediaWiki:Chameleon.css|code for Portuguese]].
 +
 
 +
==MediaWiki Messages==
 +
The Messages or texts that MediaWiki display's, do also need translation. That can't be done with the Translate Extension. It needs to be done manually by adding a subpage with the language suffix of the wanted language.
 +
For example: If you want to translate the Copyright message from English to German you open the original page which is [[MediaWiki:Copyright]]. Copy the content and then type the tile plus the language suffix into the search bar and hit enter. In the case of the example the search term would be '''MediaWiki:Copyright/de'''. Now you can paste the original text and start translating it. After you finished translation, delete the original text and safe.
  
−
The phrases in [[:Localization:All]] are used to display the names of the tabs, the names of the hierarchical names of the SDA Church organization (i.e., General Conference, North American Division, etc), the honor categories, the names of the Master Awards, and basically, anything we want to display in a template.  If a user is going to see it, it should be in [[:Localization:All]].
+
'''ATTENTION:''' These pages are only editable for administrators so get in contact with one of them. The easiest way is to join Discord, but also [[Help talk:Adding a Language|here]] is a good place to ask for help.
  
−
Each entry in [[:Localization:All]] is tagged as a section so that it can be extracted as a unit.  We've already shown how to extract a unit from this file by using [[:Template:Localize]].  If we want to add new text to a template, we need to add it to this file, and then translate it (or request a translation) in all the supported languages.  Each unit is surrounded by section tags which is how they are identified by the Localize template.  Because these words and phrases are used so widely, editing it reserved for administrators, so if you need to add a unit, let us know. Inside the section tags are <nowiki><translate></nowiki> tags which identify which part of the entry needs to be translated.  But because both of these translate tags are actually displayed when they are included, the <nowiki><translate> and </translate> tags have to be individually wrapped in <nowiki><noinclude> and </noinclude></nowiki> tags.  It's ugly, but it works and it's powerful.
+
Message that need to be translated:
 +
* [[MediaWiki:Footer Discord Notice]]
 +
* Page for the navigation:
 +
** [[MediaWiki:Home]]
 +
** [[MediaWiki:AY Honors]]
 +
** [[MediaWiki:All Honors]]
 +
** [[MediaWiki:Arts, Crafts and Hobbies]]
 +
** [[MediaWiki:Health and Science]]
 +
** [[MediaWiki:Household Arts]]
 +
** [[MediaWiki:Nature]]
 +
** [[MediaWiki:Outdoor Industries]]
 +
** [[MediaWiki:Recreation]]
 +
** [[MediaWiki:Spiritual Growth, Outreach and Heritage]]
 +
** [[MediaWiki:Vocational]]
 +
** [[MediaWiki:Investiture Achievement]]
 +
** [[MediaWiki:Master Guide]]
 +
** [[MediaWiki:Club Ministries]]
 +
** [[MediaWiki:Submit Honor Idea]]
 +
* [[MediaWiki:Pagetitle]] - only if you want to change the displayed title in the browser tab's (for your language)
 +
* [[MediaWiki:Copyright]]
 +
* [[MediaWiki:Copyrightwarning]]
 +
* [[MediaWiki:Copyrightwarning2]]
 +
* Admin Links
 +
** [[MediaWiki:Adminlinks custom project]]
 +
** [[MediaWiki:Adminlinks custom item dashboard]]
  
 
==Summary==
 
==Summary==
−
So basically, to add a new language to the wiki, request that it be added to [[:Template:GetLangSuffix]], and then translate [[:Localization:All]] to the new language. Once that's done, you can start translating regular pages.
+
So basically, to add a new language to the wiki, request that it be added to [[:Template:GetLangSuffix]], and then translate [[:Localization:All]] to the new language. Once that's done, you can start translating regular pages.

Latest revision as of 17:27, 2 October 2023

Introduction

This wiki uses the Translate extension which is described at Help:Translation. You should read that first. This page describes some of the things we did to make translation easier.

Steps

GetLangSuffix

The first thing to do when adding a new language to the wiki is to edit Template:GetLangSuffix. The template is protected though, so you may need to leave a request in the Discussion page. Administrators patrol this wiki daily, so one of us will see the request soon after you leave it.

The GetLangSuffix template returns text like /es or /de depending on where it is invoked from. It basically extracts the last element of the page name, runs it through a #switch statement, and returns a slash plus the language code if it recognizes the last element as a language code. If it is invoked from an English page, or from a page that it doesn't recognize as a translated page, it will return an empty string. Whatever it returns - an empty string, or a language code - can be tacked to the end of any page title to refer to the translated version of that page. This technique is used extensively throughout the wiki.

Localization:All

The next step is to go to the Localization:All page and create a translation for the new language. This page is a list of words and phrases that we use in templates so that we don't have to translate the templates. Templates can be very complex, and they are difficult to get right. Most templates will display text to the user by having that text in the localization page, and then using the Template:Localize template which will fetch the translated phrase based on the results returned by {{GetLangSuffix}}. For example:

{{Localize|Honor}}

will return this:

Cannot access the database: :real_connect(): (08004/1040): Too many connections

Which is admittedly not that impressive - except that if you call if from a page ending in /es, it will return "Especialidad" which is the Spanish translation of the word "Honor". That makes it quite magical. It's important to note that the argument passed to the Localize template be in English, and that it have the correct unit name. Spelling and case are important. What this means is that you should not expect

{{Localize|Especialidad}}

to work. The name of the phrase is "Honor" and it doesn't matter what language you invoke it from.

The phrases in Localization:All are used to display the names of the tabs, the names of the hierarchical names of the SDA Church organization (i.e., General Conference, North American Division, etc), the honor categories, the names of the Master Awards, and basically, anything we want to display in a template. If a user is going to see it, it should be in Localization:All.

Each entry in Localization:All is saved into a table of the database by calling a template. Those templates have two main parameter's. One is the id, that is used to get the translated text with the Template:Localize. This parameter shouldn't be touched unless you know what you are doing. To find out where a text get's used on the wiki you can use this page. The second parameter is text, that is where the translation goes.

Localization:other pages

The {{Localize}} template can take an optional second argument to specify an alternate localization page containing the localization (the first argument is the term to localize). This allows us to separate localization terms into more than one page so that the localization replacements can run faster and have a little more organization. The template is called thusly:

{{Localize|Lorem ipsum|page=alt_page}} which would search for term in Localization:alt_page (which doesn't exist - it's just an example).

If the second argument is not specified, the template defaults to using Localization:All. Here is a list of alternate Localization pages which also need to be translated:

Translating AY Honors

When translating the honors, keep in mind there are three tabs (or pages) that need to be worked on for the honor to be "completely" translated. These three tabs include:

  • Overview
  • Requirements
  • Answer Key

It would be easiest to start translating the Requirements tab first, because the other tabs depend on the requirements to generate the info.

The best order to start translating honors is to go through those that are connected directly to Investiture Achievement (the classes and curricula used for Pathfinders). These honors are usually more frequently used popular.

You can find a list of these honors by clicking this link: IA Connection

Language Specific Graphics

There are some graphics that contain text, so a new localized version of the graphic needs to be created too. Here is a list of those graphics and that is also the place to define which graphic is shown for which language.

Choose a default Bible version

Template:Bible link takes a Bible verse as a parameter and converts that to a link to biblegateway.com. This template cannot use Localization:All to pass in the Bible version because of the additional wiki markup that is added to everything the {{Localize}} template must return. This extra text is ignored by the wiki rendering software, but we need to use it to specify which version of the Bible is to be used, and the text gets added to a URL. URLs don't ignore wiki markup, so this operation fails. So we had to take a different approach.

You will need to first figure out what version string [biblegateway.com] needs to query a language-specific Bible translation. In English, this string is NKJV. Once you know what string you need to use, create a file in [[Localization:Default Bible verse/language code]]. The only thing that should be placed in the file is the string biblegateway.com needs. Do not use the Translation extension to create this file.

Configure Wikipedia links

Most wikis support interwikis - which is an easy way to link to another wiki such as wikipedia. On our wiki, we can link to a wikipedia article by adding [[W:Anax junius]] to an article. It creates a link to the wikipedia article about Anax junius. But it will take you to the English wikipedia. To make that work in another language, we have to translate Template:Localize wikipedia and change the w to something else. In Spanish, the w becomes esw. It's usually just the language code plus a w. We have several templates that automatically localize to the language of the invoking page, and some of those (such as Template:Species id) provide a link to the wikipedia article of the species (using its Latin name, so that should work in most languages).

First of all, the image needs to be created. The images we use here were created by DesignerThan. Contact him and he will be glad to create the needed image.

The created image then needs to be uploaded to the Wiki. Ask any admin for assistance to do this, or to see if DesignerThan has already done it.

For the next step, you need the link to the file. You can get that by opening the page of the image and clicking on "Original File". Now you can copy the link.

Now you are ready to do the magic. Go to the page MediaWiki:Chameleon.css and start edit mode. There you copy the code of an existing language and copy-paste it at the bottom of the page. Change the comment so it names the new language; also, change the short language name to whatever you need and exchange the link with the link of your image (only paste the parts needed, so it looks like the others).

Now the new logo should be visible if the interface is in that particular language. If it does not appear, try to empty your browser cache and reload the page.

If you want to use the same logo for multiple languages, have a look at the code for Portuguese.

MediaWiki Messages

The Messages or texts that MediaWiki display's, do also need translation. That can't be done with the Translate Extension. It needs to be done manually by adding a subpage with the language suffix of the wanted language. For example: If you want to translate the Copyright message from English to German you open the original page which is MediaWiki:Copyright. Copy the content and then type the tile plus the language suffix into the search bar and hit enter. In the case of the example the search term would be MediaWiki:Copyright/de. Now you can paste the original text and start translating it. After you finished translation, delete the original text and safe.

ATTENTION: These pages are only editable for administrators so get in contact with one of them. The easiest way is to join Discord, but also here is a good place to ask for help.

Message that need to be translated:

Summary

So basically, to add a new language to the wiki, request that it be added to Template:GetLangSuffix, and then translate Localization:All to the new language. Once that's done, you can start translating regular pages.

Retrieved from "https://wiki.pathfindersonline.org/index.php?title=Help:Adding_a_Language&oldid=600606"