Integrating Transifex and Bitbucket (Part 1)
Bitbucket is a service that lets you host and share code with other users. Bitbucket supports version control using Git and Mercurial. In this post, we’ll show you how to synchronize changes between your projects hosted in Bitbucket and your localization projects in Transifex. We’ll also post a blog on how to integrate Transifex with Bamboo, a popular continuous integration service, so don’t forget to check out our blog later this week!
What is Version Control?
If you’re unfamiliar with version control, we recommend reading our previous post on version controlled translations with Git. Version control systems (VCS) track changes to files across multiple users. Most version control systems are based around three core concepts:
- Repositories, or directories that hold code files.
- Commits, or changes to source code that are applied to a repository.
- Branches, or deviations in the code base.
Version control helps developers coordinate code changes while reducing the chances of conflicts or data loss. While there are multiple version control systems available, the examples in this article use Git simply due to its popularity.
Getting Started with Bitbucket
To start, we’ll create a new repository in Bitbucket via the web UI. After logging into your account (new accounts are free), click on the “Create” dropdown button, then click “Create Repository.”
Enter the details of your repository. You can modify the visibility settings of your project and allow other users to “fork” your project, which lets them create and work on a copy of your repository. You can also add bug tracking, add a Wiki, or select a base language for the codebase. When you’re ready, click “Create repository.”
By default, your new repository will be empty. You can use a version control system to push project files to Bitbucket, or you can import an existing repository from another code hosting service. In this example, we’ll use an existing Git repository for a NodeJS project stored locally on a Linux desktop. We’ll change the working directory to the project folder, use git remote add to add the remote repository, then push our project to the remote repository.
$ cd /home/transifex/projects/i18n
$ git remote add origin https://email@example.com/bitbucket/i18n.git
$ git push -u origin --all
Once the command completes, you should be able to browse your Git repository through the Bitbucket website.
Syncing Changes with Bitbucket
As you make changes to your local code files, you’ll need to update the Bitbucket repository. Imagine we have a file named “i18n.js,” which contains a list of all the locales used in the project. We decide to change a locale, so we update i18n.js. With Git, you can view changes between the repository’s current state and the last commit using the command
$ git status On branch master Your branch is up-to-date with 'origin/master'. Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory) modified: i18n.js no changes added to commit (use "git add" and/or "git commit -a")
Git uses a staging area to temporarily store files before committing them, allowing you to customize a commit by including or excluding certain changes. We’ll add i18n.js to the staging area, then create a new commit:
$ git add i18n.js $ git commit -m "Added new locale: es_ES" [master 6a9f8d5] Added new locale es_ES 1 file changed, 1 insertion(+), 1 deletion(-)
To update the Bitbucket repository, use the
git push command.
origin specifies the name of the remote destination, while master specifies the name of the local branch being pushed. You may be prompted for your Bitbucket account password:
$ git push origin master Password for 'https://firstname.lastname@example.org': Counting objects: 5, done. Delta compression using up to 2 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 298 bytes | 0 bytes/s, done. Total 3 (delta 2), reused 0 (delta 0) To https://email@example.com/bitbucket/i18n.git 45cff79..6a9f8d5 master -> master
If you need to pull changes from a remote repository into a local repository, for instance, to incorporate changes from another developer, use the
git pull command:
$ git pull remote: Counting objects: 3, done. remote: Compressing objects: 100% (3/3), done. remote: Total 3 (delta 2), reused 0 (delta 0) Unpacking objects: 100% (3/3), done. From https://bitbucket.org/bitbucket/i18n 6a9f8d5..776aa6d master -> origin/master Updating 6a9f8d5..776aa6d Fast-forward i18n-node-http.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
You can use
git log to review the latest changes:
$ git log commit 776aa6d5375037f009f4d4dc8acbe06bd228c214 Author: Other Developer Date: Mon Aug 24 16:41:40 2015 -0400 Changed default locale to es_ES commit 6a9f8d57dab0db5fb50d4be1b863307bd10c9c0c Author: bitbucket Date: Mon Aug 24 16:25:08 2015 -0400 Added new locale es_ES
Syncing with the Transifex Client
You can use the Transifex Client to push source changes to Transifex. The benefit to this approach is that it ensures everyone has access the latest translations. However, it could potentially make it more difficult to control who updates the latest translations and when. Features that are still in development can change entirely, and having your localizers work on text that might not appear in the final product would be a waste of time and money. Developers will also need to remember to update localization files when committing their code changes. Enforcing a push policy ensures everyone knows exactly when to sync their changes to the Transifex project.
To update your Transifex project from a local Git repository, make sure your repository is up to date with the remote Bitbucket repository by using
git pull. Install the Transifex Client if it’s not already installed. The Transifex Client is based off of the Git client and uses a similar command structure. For instance, use the
tx init command inside of your project’s root folder to create a new Transifex configuration:
$ tx init Creating .tx folder... Transifex instance [http://wpdev.transifex.com]: Creating skeleton... Creating config file... Done.
You should now have a .tx folder inside of your project. Inside of this folder is a configuration file, which contains the information used to identify the project on a Transifex server. For instance, this Node.js app has the project name “i18n” and stores its localization resources in the “locales” directory as standard JSON files.
[main] host = http://wpdev.transifex.com [i18n.enjson] file_filter = locales/.json source_file = locales/en.json source_lang = en type = KEYVALUEJSON
You can add the .tx folder to your Git repository by using
git add. When other developers pull your changes, they can use the same configuration file to connect their Transifex clients to the Transifex project.
When you’re ready to push your updated files to Transifex, use the
tx push command. The -s flag pushes source files, while the -t flag pushes translation files:
$ tx push -st Pushing translations for resource i18n.enjson: Pushing source file (locales/en.json) Pushing 'de' translations (file: locales/de.json) Pushing 'es' translations (file: locales/es.json) Done.
To pull changes into your local project folder, use
$ tx pull -a New translations found for the following languages: de, es Pulling new translations for resource i18n.enjson (source: locales/en.json) -> de: locales/de.json -> es: locales/es.json Done.
From here, simply stage, commit, then push the updated localization files to your Bitbucket repository.
Again, don’t forget to check in for part 2 of this post, Integrating Transifex with Bamboo! And until then, check out the Transifex localization website for more information about localizing digital content!