How to Contribute

[Aaron Newton]

Note: Mootools Lang now has a new github url. Please see below.

1) Verify that we don't already have that language file:
http://github.com/mootools/mootools-more/tree/master/Source/Localization
http://github.com/mootools/mootools-lang/tree/master/Docs/Localization

2) If we already have it, review it and ensure that we have all the
parts we need. Compare it to the English version (these are in
mootools-more),
which will always be complete.

3) Create a new version and post about it here. The easiest thing to
do is to create a gist for it on github: http://gist.github.com/ and
then post the link. If you are familiar with git, you can branch the
tree in the link from #1 and commit your new file. (see notes below on
github usage)

4) Ensure your name is in the header of the file. This will help us if
we need to come back and ask questions here about your work and it's
also nice to give credit where it is due.

5) If you feel like it, include the documentation file for your file
(and include your name in the authors list). You can see what the
documentation files should look like here:
http://github.com/mootools/mootools-lang/tree/master/Docs/Localization

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Getting Started with Date and FormValidator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Currently the library contains two items that output text for the user
- FormValidator and Date. We may be adding additional items in
the future, but for now, these are the only two.

Both of these came from my repository (http://www.clientcide.com/js).
There the files already had the ability to be translated and I had
numerous awesome people (some already in this group) send in
translations which I published. Some of these are incomplete - we have
added new items that need translating and the content sent in months
ago doesn't include these.

You can see the translations currently available here:

http://github.com/mootools/mootools-lang/tree/master/Source/Localization
and
http://github.com/mootools/mootools-more/tree/master/Source/Localization

You'll see we have files for numerous languages, but not all of them
are complete. The only two language files guaranteed to be complete
are
Date.English.US.js and FormValidator.English.js (because we authored
them). What we need is for you to help us translate these into
whatever languages you are fluent in.

http://github.com/mootools/mootools-more/blob/master/Source/Localization/Date.English.US.js

Most of this is pretty straight forward (hopefully). There are a few
items that are a little esoteric. For instance, 'dateOrder' is used to
determine how the culture orders the date (MM/DD/YYYY in the US, DD/
MM/
YYYY in most of Europe).

In some of the items there are variables that get substituted. For
instance 'daysUntil' has '{delta} days from now' and obviously {delta}
is going to be a number ('12 days from now').

Finally, all of the variables an be functions or other objects. For
instance, a
value that's a string could also be a function that returns a string.
This means
that some languages that need to do a transformation for a value can
compute it, while others can just return it. For example, the ordinal
for numbers in
english change for each number (1st, 2nd, 3rd, etc) but in italian the
ordinal
is always just "º". The english version looks like this:

ordinal: function(dayOfMonth){
//1st, 2nd, 3rd, etc.
return (dayOfMonth > 3 && dayOfMonth < 21) ? 'th' : ['th', 'st',
'nd', 'rd', 'th'][Math.min(dayOfMonth % 10, 4)];
},

while the italian is just:

ordinal: '&ordm;',


There is also a concept of language cascading. Let's look at
Date.English.GB.js:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/*
Script: Date.English.GB.js
Date messages for British English.

License:
MIT-style license.

*/

MooTools.lang.set('gbENG', 'Date', {

dateOrder: ['date', 'month', 'year', '/'],
cascades: ['usENG']

});

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This file gives a different dateOrder (the European style) but then
sets a cascade to the US English settings. This is because Great
Britain uses a different date order, but the rest of the values are
identical to the US English ones. Cascades are an array of other
language ids so that if a language is missing a value, the first item
in the array will be checked for that value. If not found there
either, then the second one and so on. By default, all of the
languages cascade to English as these are the files we know at least
have a value. If you're working on a language that is close to another
language, you might cascade it first to that other language and then
to English. If you have two nearly identical languages with only one
or two differences, you can describe the difference in one file and
cascade it to the other.

Your job is to look and see if we already have a date file for the
language(s) you know. If we do, see if it's complete by checking it
against the English version. If not, add the missing content. If we
don't have a language file for the one you know, then create it.

To send it in you have two options. The preferred option would be for
you to fork it on github and add your new language file(s) and then
send me (anutron on github) a pull request. Alternatively, if you
aren't familiar with git, you can just paste your files into a new
thread here on these forums and we'll pick them up. If you're
concerned with encoding (if your language requires an encoding that
you think the forums might mangle) you can email it to me - (anutron
[at] g m a i l <dot> com). If you do email it, post it here anyway.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using Git and Github
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Git works like SVN. It's nowhere near as friendly to use, mostly
because all of the tools are command line tools - no fancy UIs.

There are a lot of tutorials on how to use git on the web so I'm not
going to try and teach it to you here. If you are familiar with git
you can simply fork the main trunk
(http://github.com/mootoolsmootools-lang/tree) make changes by
altering
or adding files, then commit your changes. When you're ready to send
them to us to include, you need to push your changes back up to
github, then send a pull request to me or one of the other MooTools-
more developers. Here's what it looks like when I do it:

cd ~/Development
mkdir mootools-more
cd mootools-more
//here you would add a remote for your branch
git remote add <YourGitUserName> git://github.com/<YourGitUserName>/mootools-lang.git
git pull <YourGitUserName> master:local-master
//you are now working on a local branch called local-master
//make changes, add files, etc. then commit all the files
git commit -a
//when you're ready, push them back to git
git push <YourGitUserName> local-master:master
//now you can send me a pull request on github

I think I have all that right. There's an easier way if you don't want
to fool around with the command line tools though, so long as you
don't have to add a file (this method is only useful to submit edits).
Simply go to github, signup, and then visit the main branch:

http://github.com/mootools/mootools-lang/tree

Click "fork" and now you'll have your own copy
Browse through the directory and find the file you want to submit a
change to. Then click "edit" in the upper right hand corner. Make your
changes and enter a message in the input at the bottom for the commit
message. Save your file. Then send a pull request.

This method doesn't have a way to add a file that I can see. For new
files, if you don't want to fool around with git, just use gist
(http://gist.github.com) and post the link here.