Setting up Gulp for WordPress – and Checking TextDomains Automatically

For the first part in my ‘Automating WordPress Development‘ series I felt I should start with setting up Gulp. I resisted using Gulp (or Grunt etc) for a long time. I found it complex to setup, and it seemed like it would just be more code to maintain. Plus it used the command line; something I, as a designer, try to avoid. But eventually I got it running and found that it wasn’t as hard as I had imagined. Plus the benefits of running it outweighed the negatives of maintaining more code.

What does Gulp do?

Gulp is a task runner. It performs simple tasks on files you are working with. It can also watch files and run processes on them when they change. A common example is it can watch SASS files for changes, and then compile the SASS into CSS automatically (despite it being a very common use case I use Codekit for this and not Gulp :)).

So what do I use it for? I use it to compile theme zips, generate rtl.css files, check theme text domains, compress images, and much more. But first we need to get it running.

Setting up Gulp

I actually followed the tutorial written by Chris Coyier for setting up Grunt, called Grunt is not weird or hard. Chrises article outlines things nicely – however there are a few differences between Gulp and Grunt.

The process for setting up Gulp is:

1. Install NodeJS

Gulp uses NodeJS to run, but don’t worry – this is the easiest step. Just download the install file from NodeJS, and run it. This installs Node, and something called NPM (Node Package Manager). This is what we will use to install Gulp, and its plugins… on the command line.

2. Install Gulp

Open the command line (I like iTerm2 version 3 for the Mac). It’s a single command to install Gulp using npm.

npm install --global gulp-cli

3. Setup your project

Navigate to your project directory. For WordPress development I use the themes directory. Then run the following command:

npm init

This will create a package.json file in your project root and set the basic properties. Just follow read the text and answer the questions. You will need to do this any time you create a new project. You should then add gulp as a project dependency with:

npm install --save-dev gulp

And you’re done!

First Task

The thing is, you have gulp setup, but it doesn’t currently do anything. At all. We now need to create some tasks to run. One of the simplest tasks I have in my automation setup is checking theme textdomains are correct.

TextDomains are identifiers used in translations. They tell the WordPress localization code which language file to use for the current translation string. I setup the checker because I (currently) have 20 themes to manage, and when updating them I often copy and paste code between files – textdomains and all. So it’s good to have a reminder if I forget to change a textdomain.

You can read more about textdomains and localization in WordPress on the WordPress theme developer site.

To run tasks I need to create a gulpfile.js – since I run the same tasks on multiple themes I put this in the themes directory. Note also that it’s a js (javascript) file. All the code we’re going to write is javascript. So if you want to do something custom, it’s likely you can use some simple javascript to do it. Note that JQuery won’t work – although there are some jquery style Gulp plugins, but that’s getting ahead of ourselves 🙂

So we have the gulpfile.js ready, and now we need to install some Gulp plugins since they do most of the work for us. For this task we need two plugins. Gulp util, and Gulp Checktextdomain (all npm packages can be found on the npmjs.com website). We can install them with the following two commands (also found on npmjs package pages).

npm install gulp-util --save-dev
npm install gulp-checktextdomain --save-dev

Once installed we can code. Open up gulp.js and add the following at the top of the file:

This requires the different plugins we’ve installed, and assigns them to variables so that we can reference them in the tasks. The check text domain task looks like this:

What this code is doing is:

  1. Creating a new task called ‘checktextdomain’
  2. Grabbing the theme slug from a command line parameter (the theme folder name and textdomain should match)
  3. Select all the theme files – './' + theme_slug + '/**/*.php'
  4. Send the files down the Gulp pipe through the checktextdomain command. This is a generic command that will work with any programming language so we have to tell it all of the WordPress translation functions.

To execute the task against the twentyfifteen theme you would run the following on the command line:

gulp checktextdomain --theme twentyfifteen

However this would create an error – because I’m doing something a bit different. I am using a command line argument, which isn’t that common in the world of Gulp. I assume the reason other people don’t use this method is because they develop each theme as a separate project, so they would have different gulpfiles for each theme. I develop all of my themes on a single local WordPress install and then switch between themes as I go – so for me it makes sense to have a command line parameter so that I can specify which theme I want to test.

To add this we’re going to make use of the util plugin we installed earlier. The function is simple but I use it in a lot of the commands so I keep it as a separate function.

A couple of things to note here.

  • If there’s no command line value set then I default to ‘granule’ – this is my starter theme, and I know it will always exist so it’s a good default for both testing and fallback.
  • I am using console.log – if you use this in Gulp then it outputs content to the command line. So in this case I tell the command line which theme I am working with to confirm the selection and because I like to see the command line scroll down a long way. It makes me feel clever.

Now when we run the command it should work fine. If there are any issues with the text domain in your test theme these will be output to the command line. You can then go through and fix them, and run the test again to make sure you did it correctly.

Conclusion

If you followed this correctly (and I explained it correctly) then you should now have NodeJS set up, along with a working Gulp install, and a first Gulp task.

I’ve probably overcomplicated things – both in the way I have set Gulp up, and the way I have explained the process – so if you have any feedback or suggestions then please feel free to let me know in the comments or on Twitter.

Let me know what you think on Mastodon, or BlueSky (or Twitter X if you must).

WordPress News

The latest WordPress updates from the WPBriefs Podcast.

Related Posts

04 Nov 2016

Automating WordPress Development with Gulp, Bash, and PHP

When I wrote about the things I had learned from releasing 20 WordPress themes, I mentioned that I had automated as much as I could. One of the things I automated was the build and deployment process for my themes...
01 Apr 2015

The State of WordPress Themes #wcldn

I recently spoke on a panel at WordCamp London 2015e. Lance – who used to be the Theme Team lead at WordPress.com – asked me if I wanted to speak on a panel with him at WordCamp London 2015. I’ve...
26 Nov 2016

Generating a WordPress rtl.css with Gulp

Generating a rtl.css files is something I don’t enjoy doing. I think it’s really important that they are created since a large proportion of the world uses rtl (right to left) languages. But they are a bit of a pain...
13 Oct 2016

Lessons Learned from 20 Theme Releases on WordPress.com

In 2007 I partnered with Darren Hoyt to release Mimbo Pro, one of the earliest premium WordPress themes. In 2012 Mimbo Pro was published on wordpress.com. Last week – on October 5th 2016 to be precise – my 20th theme...
27 May 2013

WordPress: 10 Years Young, What Does The Future Hold?

WordPress is now 10 years old. I started using wordpress 9 years ago – which means I joined the WordPress community early on. The reason I chose WordPress is simply because of the fabled 5 minute install process – I...
14 Oct 2015

My Experience Submitting a Free theme to WordPress.org

I recently submitted my first free theme to WordPress.org.Kent is a theme I made for wordpress.com. It’s been code reviewed by the team there and is in use on a few hundred sites. I was considering selling it on Creative...