Internationalizing a ClassicPress plugin: Localization functions

ClassicPress PluginsThis post is part of the sub-series on Internationalizing a ClassicPress plugin which is part of the Internationalizing a ClassicPress plugin series.

There is a number of functions available in ClassicPress which can be used in localising code:

  • __() – this function takes a string and returns the translation if it exists.
  • _e() – this function takes a string and echos the translation if it exists.
  • _n() – this function allows plurals to be handled. It takes 4 parameters: the single form, the plural form, the number based on which one or the other will be displayed and the text domain.
  • _x() – this function is to prevent collisions of similar words. If you plugin uses pair in the sense of a couple of people and pair in the sense of pairing a device via bluetooth as well, collisions could arise. A foreign language might well use very different words for the two.
  • _ex() – this function is the same as the above, but echos the result rather than returning it.
  • _nx() – this function is a combination of pairs and plurals.

There are also six functions which allow us to escape the value for safe usage in attributes and HTML. Considering the above functions, the names are very descriptive:

  • esc_attr__()
  • esc_attr_e()
  • esc_attr_x()
  • esc_html__()
  • esc_html_e()
  • esc_html_x()

Translating a ClassicPress plugin

Translating a ClassicPress plugin
What is Internationalization and Localization?
Why is Internationalization and Localization important?
When should a plugin be internationalized?
Internationalizing a ClassicPress plugin: How does internationalization work?
Internationalizing a ClassicPress plugin: What is a Text Domain and how is it specified?
Internationalizing a ClassicPress plugin: Localization functions
Internationalizing a ClassicPress plugin: Which localization functions to use?
Internationalizing a ClassicPress plugin: Localizing a string
Internationalizing a ClassicPress plugin: Don't paramaterize your text domain
Internationalizing a ClassicPress plugin: Localizing a string containing a parameter
Internationalizing a ClassicPress plugin: Localizing a string including plurals
Internationalizing a ClassicPress plugin: Localizing a string including notes for the translator
Internationalizing a ClassicPress plugin: Don't include HTML markup in localization
Internationalizing a ClassicPress plugin: Don't localize URLs
Internationalizing a ClassicPress plugin: Localizing a string including line breaks
Internationalizing a ClassicPress plugin: Load plugin translations
Translating a ClassicPress plugin with Poedit: What is Poedit?
Translating a ClassicPress plugin with Poedit: Download Poedit
Translating a ClassicPress plugin with Poedit: Install Poedit
Translating a ClassicPress plugin with Poedit: Create New Translation Template
Translating a ClassicPress plugin with Poedit: Create Translations
Translating a ClassicPress plugin with GlotPress: What is GlotPress?
Translating a ClassicPress plugin with GlotPress: Download and install GlotPress
Translating a ClassicPress plugin with GlotPress: Creating administrators
Translating a ClassicPress plugin with GlotPress: Create a project
Translating a ClassicPress plugin with GlotPress: Import translation template
Translating a ClassicPress plugin with GlotPress: Import translations
Translating a ClassicPress plugin with GlotPress: Create new translation set
Translating a ClassicPress plugin with GlotPress: Export translations
Internationalizing a ClassicPress plugin
How does internationalization work?
What is a Text Domain and how is it specified?
Localization functions
Which localization functions to use?
Localizing a string
Don't paramaterize your text domain
Localizing a string containing a parameter
Localizing a string including plurals
Localizing a string including notes for the translator
Don't include HTML markup in localization
Don't localize URLs
Localizing a string including line breaks
Load plugin translations

Internationalizing a ClassicPress plugin: What is a Text Domain and how is it specified?

ClassicPress PluginsThis post is part of the sub-series on Internationalizing a ClassicPress plugin which is part of the Internationalizing a ClassicPress plugin series.

A text domain is a unique identifier which makes sure ClassicPress can distinguish between all loaded translations and apply the correct one.

The text domain should be a unique string, not used by any other translation (which would include plugins and themes) and so is recommended to match the plugin slug. So if you have a plugin with the slug of my-classicpress-plugin the text domain should be the same.

If the text domain matches the plugin slug, ClassicPress does not require the text domain to be defined in th plugin header (although it is very much recommended that it does i order to avoid collisions with other plugins or themes), but if the text domain is different to the plugin slug, then you need to include the following highlighted line in the header:

/*
 * Plugin Name: My ClassicPress Plugin
 * Author: Ian Grieve
 * Text Domain: my-classicpress-plugin
 */

One important point to remember, is that a text domain cannot include underscores.

Translating a ClassicPress plugin

Translating a ClassicPress plugin
What is Internationalization and Localization?
Why is Internationalization and Localization important?
When should a plugin be internationalized?
Internationalizing a ClassicPress plugin: How does internationalization work?
Internationalizing a ClassicPress plugin: What is a Text Domain and how is it specified?
Internationalizing a ClassicPress plugin: Localization functions
Internationalizing a ClassicPress plugin: Which localization functions to use?
Internationalizing a ClassicPress plugin: Localizing a string
Internationalizing a ClassicPress plugin: Don't paramaterize your text domain
Internationalizing a ClassicPress plugin: Localizing a string containing a parameter
Internationalizing a ClassicPress plugin: Localizing a string including plurals
Internationalizing a ClassicPress plugin: Localizing a string including notes for the translator
Internationalizing a ClassicPress plugin: Don't include HTML markup in localization
Internationalizing a ClassicPress plugin: Don't localize URLs
Internationalizing a ClassicPress plugin: Localizing a string including line breaks
Internationalizing a ClassicPress plugin: Load plugin translations
Translating a ClassicPress plugin with Poedit: What is Poedit?
Translating a ClassicPress plugin with Poedit: Download Poedit
Translating a ClassicPress plugin with Poedit: Install Poedit
Translating a ClassicPress plugin with Poedit: Create New Translation Template
Translating a ClassicPress plugin with Poedit: Create Translations
Translating a ClassicPress plugin with GlotPress: What is GlotPress?
Translating a ClassicPress plugin with GlotPress: Download and install GlotPress
Translating a ClassicPress plugin with GlotPress: Creating administrators
Translating a ClassicPress plugin with GlotPress: Create a project
Translating a ClassicPress plugin with GlotPress: Import translation template
Translating a ClassicPress plugin with GlotPress: Import translations
Translating a ClassicPress plugin with GlotPress: Create new translation set
Translating a ClassicPress plugin with GlotPress: Export translations
Internationalizing a ClassicPress plugin
How does internationalization work?
What is a Text Domain and how is it specified?
Localization functions
Which localization functions to use?
Localizing a string
Don't paramaterize your text domain
Localizing a string containing a parameter
Localizing a string including plurals
Localizing a string including notes for the translator
Don't include HTML markup in localization
Don't localize URLs
Localizing a string including line breaks
Load plugin translations

Internationalizing a ClassicPress plugin: How does internationalization work?

ClassicPress PluginsThis post is part of the sub-series on Translating a ClassicPress plugin which is part of the Translating a ClassicPress plugin series.

ClassicPress uses the gettext libraries and tools for internationalization; gettext is an old and respectable piece of software which is widely used in the world of open-source.

The basics of how it works are:

  • Developers wrap translatable strings in special gettext functions.
  • Special tools parse the source code files and extract the translatable strings into POT (Portable Objects Template) files.
  • Translators translate the strings in the POT file and save the translations into a PO file.
  • PO files are compiled to binary MO files, which give faster access to the strings at run-time.

Over the next few posts, I’ll be stepping through what you have to do while developing an internationalized plugin to allow a POT file to be created.

Translating a ClassicPress plugin

Translating a ClassicPress plugin
What is Internationalization and Localization?
Why is Internationalization and Localization important?
When should a plugin be internationalized?
Internationalizing a ClassicPress plugin: How does internationalization work?
Internationalizing a ClassicPress plugin: What is a Text Domain and how is it specified?
Internationalizing a ClassicPress plugin: Localization functions
Internationalizing a ClassicPress plugin: Which localization functions to use?
Internationalizing a ClassicPress plugin: Localizing a string
Internationalizing a ClassicPress plugin: Don't paramaterize your text domain
Internationalizing a ClassicPress plugin: Localizing a string containing a parameter
Internationalizing a ClassicPress plugin: Localizing a string including plurals
Internationalizing a ClassicPress plugin: Localizing a string including notes for the translator
Internationalizing a ClassicPress plugin: Don't include HTML markup in localization
Internationalizing a ClassicPress plugin: Don't localize URLs
Internationalizing a ClassicPress plugin: Localizing a string including line breaks
Internationalizing a ClassicPress plugin: Load plugin translations
Translating a ClassicPress plugin with Poedit: What is Poedit?
Translating a ClassicPress plugin with Poedit: Download Poedit
Translating a ClassicPress plugin with Poedit: Install Poedit
Translating a ClassicPress plugin with Poedit: Create New Translation Template
Translating a ClassicPress plugin with Poedit: Create Translations
Translating a ClassicPress plugin with GlotPress: What is GlotPress?
Translating a ClassicPress plugin with GlotPress: Download and install GlotPress
Translating a ClassicPress plugin with GlotPress: Creating administrators
Translating a ClassicPress plugin with GlotPress: Create a project
Translating a ClassicPress plugin with GlotPress: Import translation template
Translating a ClassicPress plugin with GlotPress: Import translations
Translating a ClassicPress plugin with GlotPress: Create new translation set
Translating a ClassicPress plugin with GlotPress: Export translations
Internationalizing a ClassicPress plugin
How does internationalization work?
What is a Text Domain and how is it specified?
Localization functions
Which localization functions to use?
Localizing a string
Don't paramaterize your text domain
Localizing a string containing a parameter
Localizing a string including plurals
Localizing a string including notes for the translator
Don't include HTML markup in localization
Don't localize URLs
Localizing a string including line breaks
Load plugin translations

Internationalizing a ClassicPress plugin: Series Index

ClassicPress PluginsThis series is part of a wider series on Internationalizing a ClassicPress plugin.

In the first posts on the parent series, I explained what internationalization and localization are and, in this sub-series, I am going to explain the process of internationalizing a plugin developed for ClassicPress.

Continue reading “Internationalizing a ClassicPress plugin: Series Index”

Translating a ClassicPress plugin: When should a plugin be internationalized?

ClassicPress PluginsThis series if a is part of the Translating a ClassicPress plugin series.

In the last post I discussed why internationalization was important, but the follow on from this is when should a plugin be internationalized.

When developing a plugin, it is tempting to work on the functionality first and then go back to internationize the strings afterwards. When I started developing plugins, none of them were interationalized. When I started doing so, I had to go back and find all the strings and then wrap them in the relevant functions.

New plugins, I have internationalized from the beginning and this is much less work and also means there is much less opportunity to miss a string which going back afterwards makes quite likely.

My recommendation, is to internationalize your plugin from the beginning and thereby save yourself time and errors.

Click to show/hide the Translating a ClassicPress plugin Series Index

Translating a ClassicPress plugin
What is Internationalization and Localization?
Why is Internationalization and Localization important?
When should a plugin be internationalized?
Internationalizing a ClassicPress plugin: How does internationalization work?
Internationalizing a ClassicPress plugin: What is a Text Domain and how is it specified?
Internationalizing a ClassicPress plugin: Localization functions
Internationalizing a ClassicPress plugin: Which localization functions to use?
Internationalizing a ClassicPress plugin: Localizing a string
Internationalizing a ClassicPress plugin: Don't paramaterize your text domain
Internationalizing a ClassicPress plugin: Localizing a string containing a parameter
Internationalizing a ClassicPress plugin: Localizing a string including plurals
Internationalizing a ClassicPress plugin: Localizing a string including notes for the translator
Internationalizing a ClassicPress plugin: Don't include HTML markup in localization
Internationalizing a ClassicPress plugin: Don't localize URLs
Internationalizing a ClassicPress plugin: Localizing a string including line breaks
Internationalizing a ClassicPress plugin: Load plugin translations
Translating a ClassicPress plugin with Poedit: What is Poedit?
Translating a ClassicPress plugin with Poedit: Download Poedit
Translating a ClassicPress plugin with Poedit: Install Poedit
Translating a ClassicPress plugin with Poedit: Create New Translation Template
Translating a ClassicPress plugin with Poedit: Create Translations
Translating a ClassicPress plugin with GlotPress: What is GlotPress?
Translating a ClassicPress plugin with GlotPress: Download and install GlotPress
Translating a ClassicPress plugin with GlotPress: Creating administrators
Translating a ClassicPress plugin with GlotPress: Create a project
Translating a ClassicPress plugin with GlotPress: Import translation template
Translating a ClassicPress plugin with GlotPress: Import translations
Translating a ClassicPress plugin with GlotPress: Create new translation set
Translating a ClassicPress plugin with GlotPress: Export translations

Translating a ClassicPress plugin: Why is Internationalization and Localization important?

ClassicPress PluginsThis post is part of the sub-series on Translating a ClassicPress plugin which is part of the Translating a ClassicPress plugin series.

ClassicPress is already used in many different countries where English is not the main language; and even where it is, there can be variations in the spelling of words. ClassicPress itself is internationalized and can be localized.

Plugins and themes developed for ClassicPress should also be internationalized so that they can then be localized. The developer who authors the plugin doesn’t have to do the localization (translations), but by internationalizing the plugin it means that others can easily translate the plugin without needing to modify any code.

By making translations easy to do, you increase the audience for your plugin as site admins can easily translate it into their sites language.

Click to show/hide the Translating a ClassicPress plugin Series Index

Translating a ClassicPress plugin
What is Internationalization and Localization?
Why is Internationalization and Localization important?
When should a plugin be internationalized?
Internationalizing a ClassicPress plugin: How does internationalization work?
Internationalizing a ClassicPress plugin: What is a Text Domain and how is it specified?
Internationalizing a ClassicPress plugin: Localization functions
Internationalizing a ClassicPress plugin: Which localization functions to use?
Internationalizing a ClassicPress plugin: Localizing a string
Internationalizing a ClassicPress plugin: Don't paramaterize your text domain
Internationalizing a ClassicPress plugin: Localizing a string containing a parameter
Internationalizing a ClassicPress plugin: Localizing a string including plurals
Internationalizing a ClassicPress plugin: Localizing a string including notes for the translator
Internationalizing a ClassicPress plugin: Don't include HTML markup in localization
Internationalizing a ClassicPress plugin: Don't localize URLs
Internationalizing a ClassicPress plugin: Localizing a string including line breaks
Internationalizing a ClassicPress plugin: Load plugin translations
Translating a ClassicPress plugin with Poedit: What is Poedit?
Translating a ClassicPress plugin with Poedit: Download Poedit
Translating a ClassicPress plugin with Poedit: Install Poedit
Translating a ClassicPress plugin with Poedit: Create New Translation Template
Translating a ClassicPress plugin with Poedit: Create Translations
Translating a ClassicPress plugin with GlotPress: What is GlotPress?
Translating a ClassicPress plugin with GlotPress: Download and install GlotPress
Translating a ClassicPress plugin with GlotPress: Creating administrators
Translating a ClassicPress plugin with GlotPress: Create a project
Translating a ClassicPress plugin with GlotPress: Import translation template
Translating a ClassicPress plugin with GlotPress: Import translations
Translating a ClassicPress plugin with GlotPress: Create new translation set
Translating a ClassicPress plugin with GlotPress: Export translations

Translating a ClassicPress plugin: What is Internationalization and Localization?

ClassicPress PluginsThis post is part of the sub-series on Translating a ClassicPress plugin which is part of the Translating a ClassicPress plugin series.

Internationalization (often abbreviated as i18n as there are 18 letters between the letters i and n) is the process of developing a plugin so it can easily be translated into other languages.

Localization (often abbreviated as l10n as there are 10 letters between the letters l and n) is the process of translating an internationalized plugin.

If you are a theme or plugin author, you should regard internationalization (i18n) and localization (l10n) as a requirement for your ClassicPress projects.

Click to show/hide the Translating a ClassicPress plugin Series Index

Translating a ClassicPress plugin
What is Internationalization and Localization?
Why is Internationalization and Localization important?
When should a plugin be internationalized?
Internationalizing a ClassicPress plugin: How does internationalization work?
Internationalizing a ClassicPress plugin: What is a Text Domain and how is it specified?
Internationalizing a ClassicPress plugin: Localization functions
Internationalizing a ClassicPress plugin: Which localization functions to use?
Internationalizing a ClassicPress plugin: Localizing a string
Internationalizing a ClassicPress plugin: Don't paramaterize your text domain
Internationalizing a ClassicPress plugin: Localizing a string containing a parameter
Internationalizing a ClassicPress plugin: Localizing a string including plurals
Internationalizing a ClassicPress plugin: Localizing a string including notes for the translator
Internationalizing a ClassicPress plugin: Don't include HTML markup in localization
Internationalizing a ClassicPress plugin: Don't localize URLs
Internationalizing a ClassicPress plugin: Localizing a string including line breaks
Internationalizing a ClassicPress plugin: Load plugin translations
Translating a ClassicPress plugin with Poedit: What is Poedit?
Translating a ClassicPress plugin with Poedit: Download Poedit
Translating a ClassicPress plugin with Poedit: Install Poedit
Translating a ClassicPress plugin with Poedit: Create New Translation Template
Translating a ClassicPress plugin with Poedit: Create Translations
Translating a ClassicPress plugin with GlotPress: What is GlotPress?
Translating a ClassicPress plugin with GlotPress: Download and install GlotPress
Translating a ClassicPress plugin with GlotPress: Creating administrators
Translating a ClassicPress plugin with GlotPress: Create a project
Translating a ClassicPress plugin with GlotPress: Import translation template
Translating a ClassicPress plugin with GlotPress: Import translations
Translating a ClassicPress plugin with GlotPress: Create new translation set
Translating a ClassicPress plugin with GlotPress: Export translations

Translating a ClassicPress plugin: Series Index

ClassicPress PluginsI started using WordPress when I launched this blog back in 2011 and a couple of years later started writing plugins to add missing functionality. At the end of last year I switched over to ClassicPress, a hard-fork of WordPress.

As part of my transition to ClassicPress I created new versions of my plugins which added new functionality and improved security. I had already done some work to internationalize my plugins, but took the opportunity to improve this aspect as well.

Having done so, I thought that a series on how to internationalize and localize plugins might be a useful thing to write; while the series is targeted at plugins, as I am a plugin author, the principles are the same for themes.

This series will include a couple of sub-series as well as the core series; the index for all are below and will automatically grow as the posts go live.

Continue reading “Translating a ClassicPress plugin: Series Index”

Could You Contribute To ClassicPress?

ClassicPressWhen Gutenberg for WordPress was released I did try to use it, but found it was unusable. Instead I started taking a look at ClassicPress and liked what I saw. I eventually started planning to migrate my sites from WordPress to ClassicPress and outlined my reasons for doing so.

I have also invested some time in creating new versions of my plugins for ClassicPress; these plugins are either entirely rewritten to bring them up to a certain level of coding standard, including massive improvements to the security aspect, or they are entirely new plugins (such as the Add Twitter Cards and URL Shortener).

I’ve also been involved in translating ClassicPress and writing some documentation, both areas I intend to continue helping with, and am considering looking at some of the simpler issues on GitHub.

I am only a contributor on a very small scale; many others are making much, much larger contributions. Which is the point. Behind every successful open source project is a vibrant community who is involved in both developing for and supporting the project.

Open source projects like ClassicPress need contributions from all sorts of people with all sorts of skills. All large projects like ClassicPress have a lot of work to do, especially in areas such as new infrastructure, defining roles, procedures, tools and organizing tasks.

ClassicPress Needs You

Could you contribute to ClassicPress? Check out this post on the ClassicPress blog and see how you could help out.

ClassicPress needs help from people who are developers, designers, marketers, people who are multi-lingual and can help with translations. It needs all sorts of people. Why not get involved?

If you don’t have the time to actively contribute, you can also help the project by voting on the future direction of development on the petitions site. The petitions site allows you to vote on what changes or new functionality should be introduced in future versions of ClassicPress.

This is one of the areas which separates ClassicPress from WordPress; ClassicPress lets you have a say in the future course of the project.

Check Out ClassicPress On Product Hunt

ClassicPressClassicPress v1 was released on 5th March 2019 and has now been shared onto Product Hunt, which is a website that lets users share and discover new products.

Check it out and cast your vote!

I’ve decided to go all in on ClassicPress; I moved all my sites across to it a little while ago and have also created new versions of my plugins specially for it.

If you want to use ClassicPress I also have you covered with series on installing it and migrating to it.

For those who don’t know, ClassicPress is a hard fork of WordPress 4.9; the last version before the horrendous Gutenberg block editor was forced out by Automattic (WordPress.org is ostensibly a community-led open source project, but Gutenberg was decided upon and forced by Automattic without engaging with the community).

ClassicPress has a petitions site where the community can vote on what features are added to or changes made to ClassicPress. ClassicPress is intended to be a community-led project where no-one person can dictate changes; to this end additional directors have recently been added to the board.