You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by Apache Wiki <wi...@apache.org> on 2013/09/10 16:00:09 UTC
[Cordova Wiki] Trivial Update of "CordovaTranslations" by ldeluca
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.
The "CordovaTranslations" page has been changed by ldeluca:
https://wiki.apache.org/cordova/CordovaTranslations?action=diff&rev1=32&rev2=33
Comment:
detailed information on how to manage crowdin translations
= Translating Apache Cordova =
- Apache Cordova's documentation is written in English but translations are available in a number of different languages. These languages are choosen based on volunteers who are willing to help translate from English to their native tongue. We use Crowdin, a translation and localization management platform to collaborate amongst translators and our core team.
+ Apache Cordova's documentation is written in English but translations are available in a number of different languages. These languages are choosen based on volunteers who are willing to help translate from English to their native tongue. We use Crowdin, a translation and localization management platform to collaborate amongst translators and our core team.
= The Process of Translating =
- So, you are an open source enthusiast and want to contribute to the cordova project? Just follow the steps below and you will be ready in no time:
+ If you know another language and are willing to help translate Apache Cordova, here are the steps to get started:
- * Step - 1: Join our mailing list - dev, issues, commit http://cordova.apache.org/#mailing-list
- * Step - 2: Sign ICLA http://www.apache.org/licenses/#clas
- * Step - 3: Create an account in jira apache http://issues.apache.org/jira/
- * Step - 4: Bookmark the following link: http://issues.apache.org/jira/browse/CB (this is the official url for cordova jira issues)
- * Step - 5: Introduce yourself to the community, by giving a brief introductory mail to dev@cordova.apache.org
+ * Step - 1: Create a free account with Crowdin.net [[http://cordova.apache.org/#mailing-list|http://crowdin.net]]
+ * Step - 2: Search for and find the Cordova project http://crowdin.net/project/cordova/
+ * Step - 3: Scroll down to find the languages that are currently being translated.
+ * Step - 4: Choose a language and click on the language to start contributing. ex. Spanish http://crowdin.net/project/cordova/es-ES
+ * Step - 5: Next to each of the markdown files you will see a button labelled "Translate". Clicking on that button will open a translate page where the English version of the file is on the left.
+ * Step - 6: Click on a phrase in the lefthand panel. Then type a translation in the textarea to the right. Click the "Commit Translation" button.
- If you have completed these steps, you are now ready to start contributing.
+ If a translation is already provided for a phrase you can vote it up or down. If you vote it down be sure to also include what you believe to be the correct translation.
- There are many ways you can contribute:
+ = Crowdin Administrative Scripts =
+ There are two scripts that need to be in place in your environment in order to automate the crowdin translation process.
+ 1. crowdin.yaml
+ 1. github-crowdin.sh
- 1. Find a new problem and report it as an issue.
- 1. Solve existing issues.
- 1. Propose a new feature.
- 1. Propose refactor of existing features.
- Cordova has a number of sub-projects to choose from. Fork your preferred project in github and start working on it.
+ Additionally, the crowdin-cli.jar file needs to be installed on the system. Information on the crowdin command line interface and tooling can be found here: http://crowdin.net/page/cli-tool. It includes a link to download the jar file for Windows, Mac, and Linux.
+ === crowdin.yaml ===
+ By default, the crowdin-cli will look for a configuration file called crowdin.yaml. For cordova, our crowdin.yaml file looks like this:
- '''Remember the following:'''
-
- 1. If you want to solve existing issues, look for jira issues that are 'Open' and not 'In Progress'. This indicates someone is not already working on it. Either comment on the issue or bring it up on the mailing list that you wish to try to work on the issue.
- 1. When you want to create a new issue, make sure you check whether similar issues already exist or not. This will avoid duplicates.
- 1. After creating a new jira issue, if you want to assign that issue to yourself and were unable to do so, don't worry, send a mail to dev@cordova.apache.org and it will be assigned. Assigning ownership in jira requires an additional privilege level.
- 1. Whenever you are in doubt, feel free to ask on the mailing list about where to help out and how to go about doing it. Contributors are welcome here!
-
- = Fork =
- Fork the official Apache Cordova project mirror with git. Git is the chosen revision control system for the Cordova project. There are many places to clone the code from:
-
- * from the [[http://git-wip-us.apache.org/repos/asf|official Apache servers]]
- * on [[http://github.com/apache|GitHub]] (type "cordova" into the "Find a Repository" box)
-
- Committers will typically fork from the official Apache server, since they are authorized to commit directly back to it. This is the authoritative / official repo.
-
- However, contributors should typically fork from !GitHub. This makes it easy to submit pull requests, which is the preferred method to make contributions as a non-committer. So as a contributor you should:
-
- 1. Create an account on github.com. Note that your repositories will have a URL of the form 'https://github.com/you' where the string 'you' is your userid. For the exercise here, substitute 'you' with your github userid. The official github repos that are read-only are at https://github.com/apache.
- 1. Note that Cordova has each component in a separate git repository, so there are many git repositories that compromise the entire project. They all start with "cordova-". So for this exercise we will use the fake name "cordova-x", which you should replace with the specific repository(s) you want to work with, such as "cordova-docs" or "cordova-android". The full list is on [[http://cordova.apache.org|the Cordova home page]].
- 1. On the !GitHub web interface, fork github.com/apache/cordova-x.git to your own account on !GitHub (ie, github.com/you/cordova-x.git).
- 1. From your workstation, clone your !GitHub repo (ie, github.com/you/cordova-x.git) to your workstation. For example, to clone a Cordova repository, from your workstation shell you would run (note the "https" protocol):
- {{{
- $ git clone https://github.com/you/cordova-x.git
- }}}
- You should now have a "cordova-x" directory with the extracted source.
- 1. Add a pointer back to the official repo:
- {{{
- $ cd cordova-x
- $ git remote add apache https://git-wip-us.apache.org/repos/asf/cordova-x.git
- }}}
-
- Here is a diagram of the repos and their flows:
-
- {{http://cordova.apache.org/wiki-images/contributor-git.png}}
-
- If you want to simply check out the source code and don't plan on making contributions, then you can skip !GitHub and clone directly from the Apache servers: {{{ $ git clone https://git-wip-us.apache.org/repos/asf/cordova-x.git }}}
-
- = Working in git =
- The Cordova community encourages a certain type of workflow within git. However, the below are only guidelines.
-
- == Topic Branch ==
- A good habit to get into is using topic branches for your work, while keeping the master branch untouched. You can then keep the master branch up-to-date with the main repository without worrying about merge conflicts.
-
- === Reduce Merge Conflicts ===
- By not working on the master branch, you ensure that the branch's history will not diverge from the main repository's master branch. This allows you to pull in updates from the main repository without merge conflicts.
-
- === Organize and Isolate Contributions ===
- By creating a topic branch for each contribution, you effectively isolate your changes into a single branch of history. As long as the topic branch is up-to-date, your changes will merge cleanly into the main repository. If your contributions cannot be merged cleanly, the repository maintainer may have to reject your contribution until you update it.
-
- === Easier for the Maintainer ===
- Maintainers like topic branches. It is easier to review the pull request and merge commits into the main repository.
-
- == Git Workflow ==
- Consider that you've decided to work on ticket # CB-1234 for the cordova-docs repository. You are charged with updating some documentation.
-
- === Update your master branch ===
- We're assuming you have cloned the docs repository as per the example above, and have the docs repository set up as a "apache" remote, with your own fork as the "origin". Let's first make sure your fork is up-to-date.
{{{
- $ git checkout master
- $ git pull apache master
- $ git push origin master
+ project_identifier: cordova
+ api_key: ____ourAPIkey________
+ base_path: /home/<username>/git/cordova-docs #working copy path
+
+ files:
+ -
+ source: "/docs/en/edge/**/*.md"
+ translation: "/docs/%two_letters_code%/edge/**/%original_file_name%"
+ ignore:
+ - /.git
}}}
- === Create a topic branch ===
- Let's create a new branch based off of master and call it "CB-1234".
+ It is recommended that Crowdin be pulled from a fork of the cordova-docs github project rather than directly from the main project. This script grabs the markdown .md files from the docs/en/edge directory and pushes them into the Crowdin service for each of the lanuages that are available within crowdin. For information on the api_key value, please email the crowdin project administrator: ldeluca@apache.org
+
+ === github-crowdin.sh ===
+ The github-crowdin.sh script is the script that is run to initiate the translation flow. It is a custom script that first pushes any of the changed markdown files into crowdin. It then searches through all of the languages from crowdin and downloads only those languages that are 100% translated. Finally, it pushes the translated language files back into github.
+
+ {{{#!/bin/bash
+ DOMAIN_NAME='http://api.crowdin.net'
+
+ #---CHANGE THE VARIABLES BELOW---
+ GIT_REPO_PATH=/home/<username>/git/cordova-docs
+ CROWDIN_CLI_PATH=/path/to/crowdincli
+ PROJECT_IDENTIFIER='cordova'
+ PROJECT_KEY='___sameAPIkeyAsAbove_____'
+
+ #---
+
+ cd $GIT_REPO_PATH
+ git pull origin master
+ git push origin
+
+ cd $CROWDIN_CLI_PATH
+
+ java -jar crowdin-cli.jar upload sources
+
+ curl $DOMAIN_NAME/api/project/$PROJECT_IDENTIFIER/status?key=$PROJECT_KEY > result.xml
+
+ read_dom () {
+ local IFS=\>
+ read -d \< ENTITY CONTENT
+ }
+
+ while read_dom; do
+ if [[ $ENTITY = "code" ]] ; then
+ code=( "${code[@]}" "$CONTENT" )
+ fi
+ if [[ $ENTITY = "translated_progress" ]] ; then
+ progress=( "${progress[@]}" "$CONTENT" )
+ fi
+ done < result.xml
+
+ for (( i = 0; i < ${#progress[@]}; i++ )); do
+ if [ "${progress[$i]}" = "100" ]; then
+ index=( "${index[@]}" "$i" )
+ fi
+ done
+
+ for element in "${index[@]}"; do
+ java -jar crowdin-cli.jar download -l ${code[$element]}
+ done
+
+ # fix crowdin issues:
+ echo "About to fix crowdin errors with resulting files"
+ find /home/<username>/git/cordova-docs/docs -name \*.md -exec sed -i "s/\* \* \*/---/1" {} \;
+ find /home/<username>/git/cordova-docs/docs -name \*.md -exec sed -i "s/## under the License./ under the License.\n---/g" {} \;
+ echo "Done with crowdin fix"
+
+ cd $GIT_REPO_PATH
+ git add .
+ git commit -m 'Synchronization with Crowdin'
+ git push origin
+ }}}
+ === Example Script output ===
+ After running the github-crowdin.sh script, some common messages might include:
{{{
+ Warning: Downloaded translations does not match current project configuration. Some of the resulted files will be omitted.
+ - `docs/zh/README.md'
+ Crowdin has internal caching mechanisms that prevents us from overload. Please try to download translations later.
- $ git checkout master
- $ git checkout -b CB-1234
- $ git branch
- master
- * CB-1234
}}}
+ This message can be ignored. It does not affect the downloaded files.
- You can name the topic branch anything, but it makes sense to name it after the ticket. This topic branch is now isolated and branched off the history of your master branch.
-
- === Make File Changes ===
- Let's update the accelerometer documentation for the "watchPosition" function.
{{{
- $ myeditor accelerometer/watchPosition.md
- $ git status
- modified: accelerometer/watchPostion.md
+ </FONT>
+ </TD</TR>
+ <FONT face="Helvetica">
+ A communication error occured: ""
+ </FONT>
+ </TD></TR>
+ <TR><TD>
+ <FONT face="Helvetica">
+ The Web Server may be down, too busy, or experiencing other problems preventing it form responding to requests. You may wish to try agian at a later time.
+ </FONT>
}}}
- git status shows that you have modified one file.
+ It is often the case where you will see a message that crowdin is down, like the one shown above. In which case you'll need to wait until Crowdin is back up or email their support team at: mailto:support@crowdin.net
- === Commit the File Changes ===
- git add will stage the file changes. You can then commit the staged file(s) with git commit. This is always the process to make changes to a git repository: stage, then commit.
-
- {{{
- $ git add accelerometer/watchPosition.md
- $ git status
- $ git commit
- }}}
- ==== About Commit Messages ====
- You are highly encouraged to describe your {{{git commit}}} with enough detail for someone else to understand it. In doing so, your commit message can consist of multiple lines. However, it also is highly encouraged that the first line of your commit message not exceed 50 characters. This is because some of the tooling that sits on top of git (such as the httpd apps that let you browse the repo) assume that the first line is top-level summary that is 50 characters or less. Thus there will be highlighting and truncating of the commit message using these assumptions, and it will look weird if these assumptions are not kept. And there should be a blank line between the summary and any further detailed body. For example, here is a good example of a commit message:
-
- {{{
- [CB-1234] Fixed the whizbang widget
-
- - added more sanity checking in the build script.
- - fixed the API to return the correct value in the scenario where there
- aren't any whizbangs present.
- - corrected the documentation.
-
- As an alternate to a bullet list, you could put long text here in
- paragraph form, with each line wrapped at 72 chars and blank lines
- between paragraphs.
- }}}
- Note that the first line does two things: (1) it is less than 50 characters. Subsequent lines after the first may exceed 50 characters. (2) it references a Jira issue by its id (CB-1234). Commonly, there should be a Jira issue open for defects and new features, and it is good practice for commits to point to the Jira issue they are addressing. And vice versa, you should add a comment to the Jira issue referencing the commit id(s) that contain your work. By adding the Jira number in square brackets in the commit message, you can take care of both in one step: there will be an [[http://www.apache.org/dev/svngit2jira.html|automatic comment]] added to the Jira item with the commit id, and of course the Jira item id will be in the git commit message.
-
- Long commit messages are not necessary, especially if there is a reference to a Jira item. More good advice on this topic is in the [[http://git-scm.com/book/ch5-2.html#Commit-Guidelines|Git book]].
-
- === Test Your Changes ===
- The contributor is responsible to test their changes and correct any problems with their changes before a pull request is submitted. The testing includes both verifying the function they added/touched, plus running the test suites to verify there are no regressions.
-
- When we say "run the test suites" this includes all automated tests in mobile-spec, manual tests in mobile-spec that might be affected by the change, and any platform-specific unit tests (i.e., cordova-android/test, cordova-ios/CordovaLibTests, cordova-js jake test, cordova-plugman npm test, etc.)
-
- It is recommended that you add a comment in Jira about what testing you did with your change, so a committer can understand what testing was done before they merge your change. It is also recommended that where reasonably feasible, you add automated tests to validate your change and catch any future regressions.
-
- If you are writing documentation (i.e., cordova-docs), then be aware of the [[https://github.com/apache/cordova-docs/blob/master/STYLESHEET.md|style guidelines]].
-
- === Commit More File Changes ===
- {{{
- $ myeditor accelerometer/watchPosition.md
- $ git commit -a
- }}}
- === Prepare to Send Pull Request ===
- Before sending the pull request, you should ensure that your changes merge cleanly with the main documentation repository, and that the granularity of your commits make sense.
-
- {{{
- $ git checkout master
- $ git pull apache master
- $ git checkout CB-1234
- $ git rebase master -i
- }}}
- The rebase -i step allows you to re-order or combine commits. This can help to make your commits more readable.
-
- You can do this by pulling the latest changes from the main repository back into our master. We make sure that our master is always in sync before issuing pull requests. Next, we rebase the history of the master branch onto the topic branch ticket_11. Essentially, this will rewind your divergent commits, fast-forward your topic branch to the latest commit of the master, and then re-apply your topic branch commits in order. Ensures a clean application of code changes. The [[http://book.git-scm.com/4_rebasing.html|git community book has an excellent chapter on rebasing]].
-
- Alternatively, you can use git merge master instead of git rebase master, but your topic branches history may not be as clean.
-
- Last thing is to make your code changes available from your fork.
-
- {{{
- $ git checkout CB-1234
- $ git push origin CB-1234
- }}}
- == Sharing your Changes ==
- By pushing your topic branch onto your fork, an cordova-docs maintainer can review and merge the topic branch into the main repository.
-
- === Sending a Pull Request from GitHub ===
- Pull requests sent to the [[http://github.com/apache|Apache GitHub repositories]] are used to take contributions.
-
- * Open a web browser to your GitHub account's cordova-docs fork.
- * Select your topic branch so that the pull request references the topic branch.
- * Click the Pull Request button.
-
- === Getting Noticed ===
- It is strongly recommended that you sign up for the [[http://cordova.apache.org/#mailing-list|mailing list]] before issuing a pull request. If your pull request is related to an existing JIRA issue, then add a comment to the issue with a link to your pull request. If it's not (or you're feeling too lazy to search through JIRA), then you should email the mailing-list to notify committers of your pull request.
-
- == While Waiting, Continuing Crafting Commits ==
- Since you worked on the topic branch instead of the master branch, you can continue working while waiting for the pull request to go through.
-
- Be sure to create the topic branch from master.
-
- {{{
- $ git checkout master
- $ git pull apache master
- $ git checkout -b fix_ugly_vibrate_example
- $ git branch -a
- * fix_ugly_vibrate_example
- master
- CB-1234
- }}}
- == When Your Pull Request is Accepted ==
- {{{
- $ git checkout master
- $ git pull apache master
- $ git log | more
- hey there's me! ya!
- }}}
- You can now delete your topic branch, because it is now merged into the main repository and in the master branch.
-
- PLEASE delete your topic branch on github origin, as that will automatically close your pull request. Alternatively, from the github web interface you can close your pull request while leaving your topic branch present. The goal here is for pull requests to be closed after they are merged, so we don't end up with a bunch of pull requests that appear unresolved.
-
- {{{
- $ git branch -d CB-1234
- $ git push origin :CB-1234
- }}}
- I know, deleting a remote topic branch is ugly (git push origin :CB-1234).
-
- == If Your Pull Request is Rejected ==
- In this case, you just need to update your branch from the main repository and then address the rejection reason.
-
- {{{
- $ git checkout master
- $ git pull apache master
- $ git checkout CB-1234
- $ git rebase master
- ( edit, commit, edit, commit, etc...)
- $ git push origin CB-1234
- }}}
- Then delete your topic branch (or close your pull request) as described above.
-