WordPress Localization Plugin for Sublime Text

I wrote this plugin for Sublime Text to help on a project where I am localizing a lot of text.

I found I was copy and pasting the same i18n methods over and over so I decided that there must be a relatively easy way to automate this using a plugin.

Now I select some text, press my key shortcut and the text gets replaced with the appropriate i18n method.

The plugin does not support every i18n method, just the most common methods;

  • __()
  • _e()
  • esc_html__()
  • esc_html_e()
  • esc_attr__()
  • esc_attr_e()

Not supported

  • _n() Plurals
  • _x() Context

The plugin makes one main assumption (rightly or not!) that if you select text that is encased in quotes, then that text is being used in code and as such, the plugin will not print the string.

If you’re translating a plugin or a theme, you’ll need to use a text domain to denote all text belonging to that plugin. This increases portability and plays better with already existing WordPress tools. The text domain must match the “slug” of the plugin. You can enter a text domain in the settings file;

{
    "text_domain": "some-text-domain"
}

We use key shortcuts to tell the plugin what type of text we are translating. Key shortcuts are the same as Key Bindings and you need to locate the Sublime Text User Key Bindings for your operating system and copy and paste the following into them;

// Default.sublime-keymap
[
  { "keys": ["ctrl+shift+h"],
    "command": "insert_snippet",
    "args": {
      "contents": "${0}"
    }
  },
  { "keys": ["ctrl+shift+d"],
    "command": "wp_localize",
    "args": {
      "contents": "${0}"
    }
  },
  { "keys": ["ctrl+shift+e"],
    "command": "wp_localize_and_escape_html",
    "args": {
      "contents": "${0}"
    }
  },
  { "keys": ["ctrl+shift+a"],
    "command": "wp_localize_and_escape_attr",
    "args": {
      "contents": "${0}"
    }
  }
]

For Mac OSX, the Sublime Text User Key Mappings can be found;
Sublime Text 2 -> Preferences -> Key Bindings - User

There are 3 key bindings;
ctrl + shift + d
Use this when you aren’t concerned with escaping the localized string
ctrl + shift + e
Use this when you want to make sure any HTML in the localized string is escaped
ctrl + shift + a
Use this when localized string is going to be used inside an attribute

Here are a few examples;

Normal text

<!-- String you'd like to translate -->
<p>Follow the yellow brick road</p>

<!-- ctrl + shift + d to localize string -->
<?php _e( 'Follow the yellow brick road' , 'some-text-domain' ); ?>

<!-- ctrl + shift + e to html escape -->
<?php esc_html_e( 'Follow the yellow brick road' , 'some-text-domain' ); ?>

<!-- ctrl + shift + a to attribute escape -->
<?php esc_html_attr( 'Follow the yellow brick road' , 'some-text-domain' ); ?>

Normal text surrounded with QUOTES

$var = 'Follow the yellow brick road';

# ctrl + shift + d to localize string
$var = __( 'Follow the yellow brick road' , 'some-text-domain' );

# ctrl + shift + e to html escape
$var = esc_html__( 'Follow the yellow brick road' , 'some-text-domain' );

# ctrl + shift + d to attribute escape
$var = esc_attr__( 'Follow the yellow brick road' , 'some-text-domain' );

Text with URLs and Numbers

<!-- String you'd like to translate -->
<p>I'd like 19,876.23 <a href="http://dictionary.com">words</a> in 100 to <a href="#type=sentence">5,000 sentences</a></p>

<!-- ctrl + shift + d to localize string -->
<?php printf( __( 'I\'d like %1$s <a href="%2$s">words</a> in %3$d to <a href="%4$s">%5$s sentences</a>' , 'some-text-domain' ), number_format_i18n('19876.23'), 'http://dictionary.com', 100, '#type=sentence', number_format_i18n('5000') ); ?>

<!-- ctrl + shift + e to html escape -->
<?php printf( esc_html__( 'I\'d like %1$s <a href="%2$s">words</a> in %3$d to <a href="%4$s">%5$s sentences</a>' , 'some-text-domain' ), number_format_i18n('19876.23'), 'http://dictionary.com', 100, '#type=sentence', number_format_i18n('5000') ); ?>

<!-- ctrl + shift + a to attribute escape -->
<?php printf( esc_attr__( 'I\'d like %1$s <a href="%2$s">words</a> in %3$d to <a href="%4$s">%5$s sentences</a>' , 'some-text-domain' ), number_format_i18n('19876.23'), 'http://dictionary.com', 100, '#type=sentence', number_format_i18n('5000') ); ?>

Text with URLs and Numbers surrounded with QUOTES

# String you'd like to translate
$html = 'I'd like 19,876.23 <a href="http://dictionary.com">words</a> in 100 to <a href="#type=sentence">5,000 sentences</a>';

# ctrl + shift + d to localize string
$html = sprintf( __( 'I\'d like %1$s <a href="%2$s">words</a> in %3$d to <a href="%4$s">%5$s sentences</a>' , 'some-text-domain' ), number_format_i18n('19876.23'), 'http://dictionary.com', 100, '#type=sentence', number_format_i18n('5000') );

# ctrl + shift + e to html escape
$html = sprintf( esc_html__( 'I\'d like %1$s <a href="%2$s">words</a> in %3$d to <a href="%4$s">%5$s sentences</a>' , 'some-text-domain' ), number_format_i18n('19876.23'), 'http://dictionary.com', 100, '#type=sentence', number_format_i18n('5000') );

# ctrl + shift + d to attribute escape
$html = sprintf( esc_attr__( 'I\'d like %1$s <a href="%2$s">words</a> in %3$d to <a href="%4$s">%5$s sentences</a>' , 'some-text-domain' ), number_format_i18n('19876.23'), 'http://dictionary.com', 100, '#type=sentence', number_format_i18n('5000') );

As I said, not every case is dealt with but the majority of cases are, so hopefully this is of some use to someone. Down the line, I might build on this plugin to support wp_kses and identifying plurals.

The plugin can be found here – https://github.com/eoigal/wp-localize

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s