Difference between revisions of "WesCamp"

From The Battle for Wesnoth Wiki
(Campaigns in the rep: Remove mainlined campaigns)
m (Link to GettextForWesnothDeveloper's copy of WesCamp's docs)
(39 intermediate revisions by 10 users not shown)
Line 1: Line 1:
= Wescamp-i18n =
+
''Note: As of April 4th, 2015, Wescamp appears to have been abandoned for about a year.  It might be back soon, it might not.  Someone with knowledge of the project should update this page.''
This page is dedicated to describing how to translate User-made Campaigns with the help of the project [https://developer.berlios.de/projects/wescamp-i18n Wescamp-i18n].
 
This project is hosted at berlios.de and maintained by Torangan ( david AT torangan.de ). Campaigns are uploaded
 
into the SVN rep and po-files of the campaigns are created. The po-files are updated regularly and the stats are shown at
 
http://gettext.wesnoth.org.
 
  
== If you are someone who just wants to translate a campaign ==
+
''Note: The documentation about how to mark up WML has been copied to [[GettextForWesnothDevelopers]], and documentation about translation without WesCamp has also been added to that page.''
Then, simply go to http://gettext.wesnoth.org, and download the .po file of your chosen campaign and language. Then read the information '''for translators''' on this page here, to know who to tell what you are working on, and where to submit your translations.
 
  
== How to contribute to this Project ==
+
This page is dedicated to describing how to translate user-made content with the help of the [https://github.com/wescamp WesCamp-i18n] project.
'' ''' Campaign Designers ''' ''
 
  
If you want to contribute to this project, you should follow this list:
+
This project is hosted at [https://www.github.com/ GitHub] and maintained by AI/AI0867. Add-ons are uploaded to git repositories and .po files of the content are created. The .po files are updated regularly and the stats can be found at http://gettext.wesnoth.org.
* Make sure that there is a _ (underscore) in front of the strings that can be translated.
 
* Make sure that you've got the #textdomain directives right. More information in this thread:  [http://www.wesnoth.org/forum/viewtopic.php?t=5535 Changes to translating user campaigns in wesnoth (post 0.9.1)].
 
* Notice that when you reuse official units, you can put them into the textdomain wesnoth and the game will automatically use the official translations. This does not work for textdomains from other campaigns hosted here, only for the official textdomains. It also makes sense to have the description in your textdomain and to put an #textdomain wesnoth before the [attack] part. There's no real need to translate sword, bow and friends in every campaign.
 
* If you want the names of attacks to be translateable, you need to add a field description = _"whatever" into the [attack] tag. This should be the same value as used for name= but that one can't be translated. As mentioned above, this only makes sense if you're using a new name.
 
* Please use the split objectives syntax  [http://www.wesnoth.org/forum/viewtopic.php?t=5060 as described here]. (The exact definition is in the post from Ayin at the end of the page.)
 
* If you have further questions feel free to join the irc channel #wesnoth on irc.freenode.net and ask in there. You can also ask your questions in the forum, or directly contact Torangan ( david AT torangan.de ).
 
* [[WescampInstructions|Wescamp Instructions]] - How to get started.  Written from a Mac OS X perspective, but the instructions should be valid for Linux users
 
* Subversion for Windows - a GUI: http://tortoisesvn.tigris.org
 
* If you're keen on doing everything yourself, have a look at yann's pokit available [http://ydirson.free.fr/soft/wesnoth/pokit/ here]. This is only required if you'd like to do the technical part yourself as this is usually done by Torangan. Be warned, pokit is somewhat outdated at the time of this writing and needs some derivation from the procedure described within the README.
 
  
'' ''' Translators ''' ''
+
== If you are someone who just wants to translate  ==
  
Translating user campaigns is the same as translating the normal files. All the info about this already exists in
+
Then, simply go to http://gettext.wesnoth.org, and download the .po file of your chosen add-on and language. Then read the information '''for translators''' on this page here to know whom to tell what you are working on, and where to submit your translations.
the wiki (see the links below). The files you need are located at [http://svn.berlios.de/viewcvs/wescamp-i18n/ here]. When they
 
are translated mail them to Torangan ( david AT torangan.de ).
 
Before you start translating you should
 
* look at the sub-page of the campaign you want to translate, to see if somebody is already working on it.
 
* contact Torangan and edit the subpage, so that it is known that someone is working on it.
 
If you have further questions, join the ircchannel #wesnoth on irc.freenode.net and ask them in there. Of course you will
 
also get answers if you ask your questions in the Forum, or mail Torangan.
 
  
A very useful tool for translation can be found here: [http://www.poedit.net/ poedit].
+
== Preparing your add-on for WesCamp ==
  
== Campaigns in the rep ==
+
In order for your add-on to be compatible with WesCamp’s translation tools, certain things must be done. This section describes what must be done and what should be done anyway.
Here is a list of the campaigns that are already in the repository. The subpages are used to coordinate your and our
+
 
efforts. We will put in there a list of the translators working on the specific campaign.
+
=== Encoding and Filenames ===
* [[CampaignANewOrder|A New Order]]
+
 
* [[CampaignDelfadorsMemoirs|Delfador's Memoirs]]
+
Your files '''must''' be in UTF-8 (not whatever other encoding you might happen to be using/want to use, such as ISO-8859-15) and there '''must''' be '''no''' spaces in any of your add-on’s files’ names.
* [[CampaignFlightFreedom|Flight to Freedom]]
+
 
* [[CampaignEliador|Invasion of Eliador]]
+
=== The textdomain declaration ===
* [[CampaignMageRepublic|Mage Republic]]
+
First, your add-on must declare a textdomain. To do this, make sure something like the following is inside of your _main.cfg:
* [[CampaignMysteryCampaign|Mystery Campaign]]
+
 
* [[CampaignOrcishIncursion|Orcish Incursion]]
+
<syntaxhighlight lang=wml>
* [[CampaignSavingElensefar|Saving Elensefar]]
+
[textdomain]
* [[CampaignNewThreat|The Dark Elves: A New Threat]]
+
    name="wesnoth-Son_of_Haldric"
* [[CampaignUnrest|Unrest in Elfland]]
+
    path="data/add-ons/Son_of_Haldric/translations"
 +
[/textdomain]
 +
</syntaxhighlight>
 +
 
 +
Note that to be compatible with WesCamp’s tools, the part of the textdomain after ''wesnoth-'' must match your add-on’s directory name. In this example, the add-on’s directory is ''Son_of_Haldric'', thus we would get ''wesnoth-Son_of_Haldric''.
 +
 
 +
The ''translations'' directory is where compiled translations would go.
 +
 
 +
=== The textdomain bindings ===
 +
 
 +
All files with translatable strings must be bound to your domain. See the example below:
 +
 
 +
<syntaxhighlight lang=wml>
 +
#textdomain wesnoth-Son_of_Haldric
 +
 
 +
[unit_type]
 +
    id=Mu
 +
    name= _ "Mu"
 +
    # ...
 +
[/unit_type]
 +
</syntaxhighlight>
 +
 
 +
Note that you can reuse translations for strings in mainline domains by using multiple textdomain bindings or a gettext helper file (which will be explained later):
 +
 
 +
<syntaxhighlight lang=wml>
 +
# textdomain wesnoth-Son_of_Haldric
 +
 
 +
[unit_type]
 +
    id=Mu
 +
    name= _ "Mu"
 +
    # ...
 +
 
 +
    [attack]
 +
        id=sword
 +
        #textdomain wesnoth-units
 +
        description= _ "sword"
 +
        # ...
 +
    [/attack]
 +
 
 +
    #textdomain wesnoth-Son_of_Haldric
 +
    # ...
 +
[/unit_type]
 +
</syntaxhighlight>
 +
 
 +
Of course, if you use bindings for multiple textdomains, make sure the right parts of the file are bound to the right domains. Also, never try to use the mainline campaigns’ domains, for there is no guarantee that the mainline campaigns will be available on all setups. So, only use the core domains: wesnoth, wesnoth-editor, wesnoth-lib, wesnoth-help, wesnoth-test, and wesnoth-units.
 +
 
 +
Note that it is highly recommended that the first textdomain binding be on the first line of the file. Otherwise, odd stuff may happen.
 +
 
 +
=== The translatable strings ===
 +
 
 +
To mark a string as translatable, just put an underscore ( _ ) in front of the string you wish to be marked as translatable, like the example below:
 +
 
 +
<syntaxhighlight lang=wml>
 +
name= _ "Mu"
 +
</syntaxhighlight>
 +
 
 +
Note that there are certain things you should never do. For example, '''never''' mark an empty string as translatable, for wmlxgettext (the tool that extracts strings from WML) will abort upon detecting one. Therefore, what is seen below should never be done:
 +
 
 +
<syntaxhighlight lang=wml>
 +
name= _ ""
 +
</syntaxhighlight>
 +
 
 +
Also, never put macro arguments in a translatable string, for it will not work. The reason for this is that the preprocessor does its job before gettext, thus gettext will try to replace a string that does not exist. Therefore, what is shown below should not be done:
 +
 
 +
<syntaxhighlight lang=wml>
 +
name= _ "{TYPE} Mu"
 +
</syntaxhighlight>
 +
 
 +
To show why it will not work:
 +
 
 +
<syntaxhighlight lang=wml>
 +
#define UNIT_NAME TYPE
 +
    name= _ "{TYPE} Mu"
 +
#enddef
 +
 
 +
{UNIT_NAME ( _ "Sword")}
 +
{UNIT_NAME ( _ "Bow")}
 +
</syntaxhighlight>
 +
 
 +
Translation catalogues would have this: "{TYPE} Mu", therefore gettext will look for it even though it will not exist because we, in fact, have these after the preprocessor is done:
 +
 
 +
<syntaxhighlight lang=wml>
 +
name= _ "Sword Mu"
 +
name= _ "Bow Mu"
 +
</syntaxhighlight>
 +
 
 +
Since those are not in the catalogues, they will not get translated.
 +
 
 +
If you think a translatable string needs additional guidance to be translated properly, you can provide a special comment that will be seen by the translators. Just begin the comment with '#po:' above the string in question:
 +
 
 +
<syntaxhighlight lang=wml>
 +
#po: "northern marches" is *not* a typo for "northern marshes" here.
 +
#po: In archaic English, "march" means "border country".
 +
story=_ "The orcs were first sighted from the north marches of the great forest of Wesmere."
 +
</syntaxhighlight>
 +
 
 +
=== The gettext helper file ===
 +
 
 +
A gettext helper file is a lovely file that makes reusing mainline translations nice and easy. It is also more wmllint-friendly.
 +
 
 +
Here is an example of a gettext helper file:
 +
 
 +
<syntaxhighlight lang=wml>
 +
#textdomain wesnoth-lib
 +
 
 +
#define STR_ICE
 +
_"Ice" #enddef
 +
 
 +
#textdomain wesnoth-units
 +
 
 +
#define STR_SWORD
 +
_"sword" #enddef
 +
</syntaxhighlight>
 +
 
 +
A typical name for gettext helper files is ''mainline-strings.cfg''.
 +
 
 +
To use it, just wire it into your add-on and use the macros:
 +
 
 +
<syntaxhighlight lang=wml>
 +
[attack]
 +
    id=sword
 +
    name={STR_SWORD}
 +
    # ...
 +
[/attack]
 +
 
 +
[terrain_type]
 +
    id=ice2
 +
    name={STR_ICE}
 +
    # ...
 +
[/terrain_type]
 +
</syntaxhighlight>
 +
 
 +
=== Getting your add-on into WesCamp ===
 +
 
 +
Now, to get your add-on into WesCamp, all you do is put this line into your add-on’s .pbl file and upload to the add-ons server:
 +
 
 +
  translate=true
 +
 
 +
And your add-on will eventually be uploaded to WesCamp.
 +
 
 +
== How to contribute to this project ==
 +
 
 +
=== Translators ===
 +
 
 +
Translating add-ons works the same as translating mainline. All of the information about this already exists in the wiki (see the links below). The files you need are located in the project’s [https://github.com/wescamp Github repositories] (they might take a bit of effort to locate. Alternatively, you can use [http://gettext.wesnoth.org gettext.wesnoth.org]). When they are translated, send them to [mailto:AI0867_AT_gmail.com AI/AI0867].
 +
 
 +
Before you start translating you should:
 +
* Look at the subpage of the add-on you wish to translate to see if someone is already working on it.
 +
* Contact the translation team for your target language for guidance.
 +
 
 +
If you have questions, join the [irc://irc.freenode.net/wesnoth #wesnoth] channel on the Freenode IRC network and ask in there. Of course, you will also get answers if you ask your questions in the [http://forums.wesnoth.org/viewforum.php?f=7 Translations & Internationalization forum], or e-mail [mailto:AI0867_AT_gmail.com AI/AI0867].
  
 
== See Also ==
 
== See Also ==
  
* [[GettextForTranslators|GetText for Translators]] - how to translate Wesnoth under [[GetText]]
+
* [[GettextForTranslators|GetText for Translators]] - how to translate Wesnoth using [[GetText]]
 
* [[WesnothTranslations|Wesnoth Translations]]
 
* [[WesnothTranslations|Wesnoth Translations]]
 
* [[TranslatorsGuide|Translators' Guide]]
 
* [[TranslatorsGuide|Translators' Guide]]
 
* [http://gettext.wesnoth.org Translation statistics]
 
* [http://gettext.wesnoth.org Translation statistics]
* [https://developer.berlios.de/projects/wescamp-i18n Wescamp-i18n project at Berlios.de]
+
* [https://github.com/wescamp WesCamp project at Github]
* [http://svn.berlios.de/viewcvs/wescamp-i18n/ Wescamp-i18n SVN-Tree]
+
* [[Wescamp.py_Instructions|Wescamp for Maintainers]]
  
 
[[Category:Translations|*]]
 
[[Category:Translations|*]]
 
[[Category:Campaigns]]
 
[[Category:Campaigns]]

Revision as of 12:10, 26 May 2018

Note: As of April 4th, 2015, Wescamp appears to have been abandoned for about a year. It might be back soon, it might not. Someone with knowledge of the project should update this page.

Note: The documentation about how to mark up WML has been copied to GettextForWesnothDevelopers, and documentation about translation without WesCamp has also been added to that page.

This page is dedicated to describing how to translate user-made content with the help of the WesCamp-i18n project.

This project is hosted at GitHub and maintained by AI/AI0867. Add-ons are uploaded to git repositories and .po files of the content are created. The .po files are updated regularly and the stats can be found at http://gettext.wesnoth.org.

If you are someone who just wants to translate

Then, simply go to http://gettext.wesnoth.org, and download the .po file of your chosen add-on and language. Then read the information for translators on this page here to know whom to tell what you are working on, and where to submit your translations.

Preparing your add-on for WesCamp

In order for your add-on to be compatible with WesCamp’s translation tools, certain things must be done. This section describes what must be done and what should be done anyway.

Encoding and Filenames

Your files must be in UTF-8 (not whatever other encoding you might happen to be using/want to use, such as ISO-8859-15) and there must be no spaces in any of your add-on’s files’ names.

The textdomain declaration

First, your add-on must declare a textdomain. To do this, make sure something like the following is inside of your _main.cfg:

[textdomain]
    name="wesnoth-Son_of_Haldric"
    path="data/add-ons/Son_of_Haldric/translations"
[/textdomain]

Note that to be compatible with WesCamp’s tools, the part of the textdomain after wesnoth- must match your add-on’s directory name. In this example, the add-on’s directory is Son_of_Haldric, thus we would get wesnoth-Son_of_Haldric.

The translations directory is where compiled translations would go.

The textdomain bindings

All files with translatable strings must be bound to your domain. See the example below:

#textdomain wesnoth-Son_of_Haldric

[unit_type]
    id=Mu
    name= _ "Mu"
    # ...
[/unit_type]

Note that you can reuse translations for strings in mainline domains by using multiple textdomain bindings or a gettext helper file (which will be explained later):

# textdomain wesnoth-Son_of_Haldric

[unit_type]
    id=Mu
    name= _ "Mu"
    # ...

    [attack]
        id=sword
        #textdomain wesnoth-units
        description= _ "sword"
        # ...
    [/attack]
   
    #textdomain wesnoth-Son_of_Haldric
    # ...
[/unit_type]

Of course, if you use bindings for multiple textdomains, make sure the right parts of the file are bound to the right domains. Also, never try to use the mainline campaigns’ domains, for there is no guarantee that the mainline campaigns will be available on all setups. So, only use the core domains: wesnoth, wesnoth-editor, wesnoth-lib, wesnoth-help, wesnoth-test, and wesnoth-units.

Note that it is highly recommended that the first textdomain binding be on the first line of the file. Otherwise, odd stuff may happen.

The translatable strings

To mark a string as translatable, just put an underscore ( _ ) in front of the string you wish to be marked as translatable, like the example below:

name= _ "Mu"

Note that there are certain things you should never do. For example, never mark an empty string as translatable, for wmlxgettext (the tool that extracts strings from WML) will abort upon detecting one. Therefore, what is seen below should never be done:

name= _ ""

Also, never put macro arguments in a translatable string, for it will not work. The reason for this is that the preprocessor does its job before gettext, thus gettext will try to replace a string that does not exist. Therefore, what is shown below should not be done:

name= _ "{TYPE} Mu"

To show why it will not work:

#define UNIT_NAME TYPE
    name= _ "{TYPE} Mu"
#enddef

{UNIT_NAME ( _ "Sword")}
{UNIT_NAME ( _ "Bow")}

Translation catalogues would have this: "{TYPE} Mu", therefore gettext will look for it even though it will not exist because we, in fact, have these after the preprocessor is done:

name= _ "Sword Mu"
name= _ "Bow Mu"

Since those are not in the catalogues, they will not get translated.

If you think a translatable string needs additional guidance to be translated properly, you can provide a special comment that will be seen by the translators. Just begin the comment with '#po:' above the string in question:

#po: "northern marches" is *not* a typo for "northern marshes" here.
#po: In archaic English, "march" means "border country".
story=_ "The orcs were first sighted from the north marches of the great forest of Wesmere."

The gettext helper file

A gettext helper file is a lovely file that makes reusing mainline translations nice and easy. It is also more wmllint-friendly.

Here is an example of a gettext helper file:

#textdomain wesnoth-lib

#define STR_ICE
_"Ice" #enddef

#textdomain wesnoth-units

#define STR_SWORD
_"sword" #enddef

A typical name for gettext helper files is mainline-strings.cfg.

To use it, just wire it into your add-on and use the macros:

[attack]
    id=sword
    name={STR_SWORD}
    # ...
[/attack]

[terrain_type]
    id=ice2
    name={STR_ICE}
    # ...
[/terrain_type]

Getting your add-on into WesCamp

Now, to get your add-on into WesCamp, all you do is put this line into your add-on’s .pbl file and upload to the add-ons server:

  translate=true

And your add-on will eventually be uploaded to WesCamp.

How to contribute to this project

Translators

Translating add-ons works the same as translating mainline. All of the information about this already exists in the wiki (see the links below). The files you need are located in the project’s Github repositories (they might take a bit of effort to locate. Alternatively, you can use gettext.wesnoth.org). When they are translated, send them to AI/AI0867.

Before you start translating you should:

  • Look at the subpage of the add-on you wish to translate to see if someone is already working on it.
  • Contact the translation team for your target language for guidance.

If you have questions, join the #wesnoth channel on the Freenode IRC network and ask in there. Of course, you will also get answers if you ask your questions in the Translations & Internationalization forum, or e-mail AI/AI0867.

See Also