You're Doing It Wrong: Don't hack Drupal core to change text

There are many good ways to accomplish the same goals in Drupal, due to its flexible APIs and ease of development. That said, there can also be many wrong ways of approaching a problem, methods which are obviously wrong to experienced developers but which may seem like a quick & easy solution for an inexperienced developer. Lets be clear about this - doing things the wrong way will almost always lead to headache and grief in the long term, so it's best to avoid these. This new regular series, dubbed "You're Doing It Wrong" or #YDIW, will highlight some of the ways not to solve problems.

A frequent small task that Drupal developers find themselves needing to do is to change some of the interface text from either Drupal's core files or a contributed module. There are two very simple ways of doing this - the right way and the wrong way.

The Right Way?

Supposing a client has a site for promoting their products and wants to let people provide reviews directly on corresponding product pages (presuming some level of moderation). The client might then decide that instead of pages saying "Comments" and "Add new comment", they would prefer to have the pages say "Reviews" and "Add a new review".

The wrong way of changing built-in text in Drupal is to open up the original file and directly make the changes. This might not seem like a big deal, especially given that the two lines are in a single file (comment-wrapper.tpl.php) in Drupal 7. But what if the client didn't like the word "node" and wanted to change it to "article" or "post", like Wordpress uses, how many files would have to be changed for that?

The right way of changing text is via string overrides. Drupal has lots of support for full internationalization of your content & site text, but for minor changes you don't need to go through all of that headache and can instead use this simple method.

Step One - Finding the text

There are two steps to changing the text. The first step is search for the exact string you would like to replace. There are three quick things to keep in mind when looking for this string:

  1. The text must be wrapped in the t() function in order to be changeable, so if someone hardcoded the text into a module file you can't use these techniques; if you happen to find text that is not wrapped in t() you should submit an issue to the module's issue queue to have the module fixed, preferably with a patch file too :)
  2. The text is case-sensitive, so what is displayed as "comment" in one location will be a different string to "Comment" displayed in another location.
  3. You can only change the entire string that is passed to t(), so e.g. changing the word "comment" to "review" won't also automatically change "add new comment" to say "add new review", you must handle these as two separate strings.

In our example we would like to change the phrase "Add a new comment", which is on line 48 of the file "comment-wrapper.tpl.php" in Drupal 7 (correct as of Drupal 7.2, the line number may change in subsequent releases).

Step Two - Changing the text

Once the exact text has been found, there are two options for changing it.

Option #1: code

If you edit the settings.php file for your site and scroll down to near the end you'll find the following if your site is Drupal 6:

1
2
3
4
# $conf['locale_custom_strings_en'] = array(
#   'forum'      => 'Discussion board',
#   '@count min' => '@count minutes',
# );

The settings.php file for Drupal 7 contains the following instead (note values are nested within an additional array):
1
2
3
4
# $conf['locale_custom_strings_en'][''] = array(
#   'forum'      => 'Discussion board',
#   '@count min' => '@count minutes',
# );

If you uncomment those lines (remove the # symbols at the start of the lines) you'll now see the phrase "Discussion board" used in place of the single word "forum". For our examples above the resulting lines should be as follows:
Drupal 6:
1
2
3
4
$conf['locale_custom_strings_en'] = array(
  'Comments' => 'Reviews',
  'Add new comment' => 'Add new review',
);

Drupal 7:
1
2
3
4
$conf['locale_custom_strings_en'][''] = array(
  'Comments' => 'Reviews',
  'Add new comment' => 'Add new review',
);

If you'd prefer not to fiddle with the settings.php file for your site you might want to try option #2 instead.

Option #2: Module

As it happens there there's a module for making it super easy to change the string overrides right from the Drupal admin - the aptly named String Overrides module! If the thought of changing some lines in a PHP file eeks you out, you might want to try this simple module instead. Like any other module, simply download it to your sites/all/modules/contrib directory (you do put all of your contrib modules there, don't you?), enable the module and then go to its settings page where you'll see a very simple interface. Easy peasie!

Recap

  • Changing text from the Drupal interface is easy.
  • Find the text you wish to change, it'll be wrapped in a t() function call.
  • Either add a string override line to the settings.php page, or..
  • Use the String Overrides module.

Where this post came from

At Bluespark Labs we often are given the job of expanding upon existing work built by others. Because not everybody starts a project knowing how to properly work with Drupal, often times we will find some decisions made by the previous developers that make us scratch our heads. This particular issue arose because the original developer for one site we inherited was not aware of the string overrides system and hacked up several core files, and contrib modules, to make textual changes that were being asking for. Thankfully, now you know how to do it the right way.

More soon..

Don't forget that this is the first of a new, ongoing series and there will be many more to come, so check back often!

12 Comments

Ryan's picture
Ryan -

So it's 'wrong' to copy comment-wrapper.tpl.php into your theme and make changes?

Damien McKenna's picture
Damien McKenna -

Ryan, thanks for the feedback. Copying the template file would certainly work, maybe I should have picked an example that wasn't solvable by using just the template layer ;-)

Fabianx's picture
Fabianx -

User module. If people hack core, they always hack the user.module, because:

* e-mail -> email
* Create new Account -> Register
* Login -> Sign-in
* Login -> Sign In
* Login -> Log in

and other strings in there that absolutely need changing, etc.

And yes: Hacked Core is a bad thing to have ...

Best Wishes,

Fabian

Katrin's picture
Katrin -

The template approach doesn't work when you have a multilingual site and already have translations in place (unless you want to update all your translations to match the new original string)

Alejandro Garza's picture

Good post; I love the idea of a series of "don't do it like that" articles =)

Just wanted to point out that sometimes the text to change or add is a bit more out of reach; that's when you should reach for any of the several _alter hooks. For instance hook_form_alter() to change/add/remove forms.

Damien McKenna's picture
Damien McKenna -

Thanks for your feedback, Alejandro. That is certainly a valid point, if the desired textual changes are so detailed sometimes it can be easier to just use a hook.

Jamie Hollern's picture
Jamie Hollern -

I enjoyed reading that and to be honest, might not have thought of that solution, even though I regard myself as a good Drupal developer. I really like the idea of a series of articles like this too.

Gábor Hojtsy's picture

There is this nice issue to add full-on support for English in locale module, to stop special casing it, so these kind of overrides can be done just with core on a UI (among other notable benefits). Please see and support http://drupal.org/node/1266318

devisdetective.com's picture

Just what I was looking for, thanks for posting the drupal link. :)

lxy_yuhai's picture
lxy_yuhai -

Just wanted to point out that sometimes the text to change or add is a bit more out of reach; that's when you should reach for any of the several _alter hooks. For instance hook_form_alter() to change/add/remove forms.

MattJ's picture
MattJ -

Thank you for this post. I had needed to change a string and this was very helpful. Appreciate it :)

Add Your Comment

Case studies

Roomify — Powerful online booking. Open source comes to travel.
Italy Magazine — Italian lifestyle, travel, and culture.
Integrative Nutrition — 25,000 websites on a single platform
Sandusky Radio — 11 Radio Station Websites in 6 Months, within Budget

Subscribe