The Custom Text plugin displays text from system language files as specified by the {exp:custom_text} tag. It also allows the use of custom language files to contain often used text.

Example Usage
This EE Code:

Returns this text:

This EE Code:

Returns this text:

This EE Code:

Returns this text:

Parameters

- The string parameter tells the Custom Fields plugin to display text that corresponds to the provided parameter.

If a file parameter is given in the same tag {exp:custom_text string=“string” file=“file”}, that file will be used to locate the string. If no file parameter is given in a tag {exp:custom_text string=“string”}, the Custom Fields plugin will see if the string is available from an already loaded file. If the string cannot be located, the string itself will be displayed.

- The file parameter tells the Custom Fields plugin to load a language file that corresponds to the provided parameter.

Individual {exp:custom_text file=“file”} tags should be loaded as early in the template as possible, as their values will only be available to subsequent {exp:custom_text string=“string”} tags.

The file parameter should contain the name of the module, plugin, or extension from which you want to use strings. It should be provided exactly as it appears in the languages folder (without the prefix “lang.” or suffix ”.php”). If no file parameter is given anywhere in the template, the plugin will attempt to use the “lang.my_custom_text.php” file.

The user’s default language is always used (or if the user is anonymous, the system’s default language is used).

If more than one file contains the same string key, unexpected results may occur. If this happens, be sure to specify the exact file to use with a {exp:custom_text string=“string” file=“file”} tag.

{exp:custom_text} tags can be placed in different levels within embedded templates. {exp:custom_text string=“string”} tags should work as long as an {exp:custom_text file=“file”} tag is somewhere upstream.

Custom Language Files
This most useful aspect of this plugin is that it can be used to create custom language files. Simply place the included “lang.my_custom_text.php” file in your language folders.

(my_custom_text can be any string, though to avoid conflicting with other files you should probably use a prefix e.g. mydomain_custom_text or myname_custom_text. Additionally, for best results be sure the string keys within the language file are unique, again use a prefix e.g. mydomain_string1, mydomain_string2, etc. Language file keys must be entirely lowercase.)

Versions
v0.2.0: First Release.
v0.3.0: If no file parameter is given and the string cannot be loaded from memory, the plugin will check for a “lang.my_custom_text.php” file. (This file is now included in the package by default.)

Wiki’d.

I updated the package, and included an example “lang.my_custom_text.php” file. See original post for details.

One more note: Language file keys can contain spaces, however they must be entirely lowercase.

e.g.
will work: “custom_text” => “Custom Text”
will work: “custom text” => “Custom Text”
will not work: “Custom_Text” => “Custom Text”
will not work: “Custom Text” => “Custom Text”

UPDATE: While language file keys can contain spaces, if you use the Translation Utility to translate strings with spaces in their keys in them, they will not be saved properly.

Here’s an example of how I use this plugin:

I’m creating a multilingual website, and I’ve used a method similar to one described on these forums and in the wiki (multiple custom fields for each language).

However, categories are very difficult to use with this method because you can’t have more than one name for a category. (There are some workarounds posted here, namely using the category description field to hold the category name in the other language, but I wanted to actually use the category description field, and this fails if you have more than two languages.)

So all I have to do is create the categories in EE with their English name (or any name that correlates to the string’s key in my custom language files), and use this plugin within my templates to translate the category name like so:

(“waz_” is my custom prefix I’m using so as to not clash with other language variables. Also, this will pull the string from the default “lang.my_custom_text.php” file as described in the posts above. In my “lang.my_custom_text.php” file I have the following (which is translated within the “lang.my_custom_text.php” files for each language:

update: i figured it out!
cool!

what i did:
i used a combination of your plugin with the translation idea: http://www.eewiki.com/wiki/Multi_language_site

so instead of using a fixed prefix,  i used:

<?php echo $lang ?>_{category}

in lang.my_custom_text.php I defined my different categories:
“nl_about” =>
“wij zijn”,

“nl_contact” =>
“contacteer ons”,

“fr_about” =>
“nous sommes”,

“fr_contact” =>
“contactez nous”,

it works perfect

the only pity is that i have to adapt the file manually each time a category is added…

wazdog - 19 June 2006 08:38 PM

If the string cannot be located, the string itself will be displayed.

GREAT plugin. Just what I need. Though, I do have a problem. When the string can’t be located in the language file, the string itself ideed is displayed, but in lowercase.

For example:

..will return “articles” instead of “Articles” when not found in the language file.

Am I doing anything wrong? If not, is there some way to modify the plugin so that the actual original string is returned?

Hi, is this plugin being maintained anywhere?  And does it take into consideration the $language variable if there are multiple language folders? (i.e., is the plugin smart enough to parse language/french/lang.my_file.php instead of language/english/lang.my_file.php when the $language global variable is “french” ?)

cheers

aha, I just found the localize_text plugin.