Previously we talked about some files which are included in most pages of the osCommerce system, header.php, column_left.php, column_right.php, and footer.php. All four of these files deal directly with the visual appearance of osCommerce. There are some other files which are also included in each page with in the system. application_top.php and application_bottom.php are two of these files. application_top.php is basically the bootstrap include for each page. It contains calls to connect to the database, constant definitions, etc. And application_bottom.php serves as a clean up file for the page.

There is also another file included, the language file, and that's what I'm going to center this discussion on today. The architecture of osCommerce provides support provides for localization through the use of language files. Out of the box, the default installation of osCommerce provides support for three languages, English, German, and Spanish. It is through the use of these language files that the system is able to dynamically adjust to the chosen language of a visitor to your cart. For example if a user to your cart modifies their personal language setting to German the labels, buttons, and other text on the pages of your cart will appear in German. Same thing for a user choosing English or Spanish, through some available osCommerce contributions or simply by doing it yourself other languages can also be added by following the existing model.

If you look at the code for a visual page, somewhere near the top you'll find a line of code that looks similar to this:

require(DIR_WS_LANGUAGES . $language . '/' . FILENAME_CREATE_ACCOUNT);

Of course we can expect that DIR_WS_LANGUAGES is a defined constant for the 'languages' folder and that assumption would be correct, this folder can be found within the 'includes' folder. '$language' is a PHP variable, if you are new to PHP variables always begin with the '$' character, its value is the language chosen by visitor to your cart, i.e. English. FILENAME_CREATE_ACCOUNT is a defined constant, file name constants are defined in the filename.php file which is also found in the 'includes' folder. In this specific example FILENAME_CREATE_ACCOUNT is defined as create_account.php. So when your web server reads this file it sees:

require(languages/english/create_account.php);

So now lets go back and take a look at the languages folder. Inside we see three files english.php, german.php, and espanol.php. We also see three folders with similar names, English, German, and Espanol. What I am going to explain here applies equally to all three default languages, but for the sake of simplicity I'm going to refer to English.

The english.php file is a general purpose language file. Meaning that it contains language definitions which are applied across all pages. Let's take another look at some example code:

define('HEADER_TITLE_TOP', 'Top');

This is taken from the english.php file and defines the word 'Top' which appears at the far left of the breadcrumbs trail on the navigation bar. I specifically used this example because it appears on every page of an osCommerce cart and because it's frequently a piece of text that site owners want to change when they start customizing things. So lets say rather than 'Top' we wanted it to say 'Home', we would just simply modify the code to look like this:

define('HEADER_TITLE_TOP', 'Home');

Rather than 'Top' in the breadcrumbs trail, 'Home' would appear on every page of the cart. As developers we always want to be able to make changes in a single location and have the change appear everywhere it's used. english.php accomplishes this goal for words that are used in multiple pages within the cart.

Now an osCommerce shopping cart is made up with a few dozen visual pages, most with text and several labels. In theory we could include all of those definitions within the english.php file, after all it is available to every page in the cart. However if we were to do so the english.php file would grow rather large. Performance would be impacted not to mention it would become fairly difficult to manage. So to address that issue the architecture of osCommerce uses language files which are specific to the individual pages in the cart.

Lets take a look inside the 'languages/english' folder. Inside we find a list of files that basically mirror the file names from the root folder of the osCommerce cart. It makes it all fairly easy to follow because the language file has the same name as the visual file, it's just in a different location. Browsing the list of files we can find create_account.php from our example above. Inside this create_account.php file we will find the English translations of the labels and text that are specific to the 'Create Account' page.

So lets do a practical example. After you have done a default installation of osCommerce, you have this working shopping cart. But right in the middle of your home page is some text along the lines of 'Congratulations your installation of osCommerce was successful......" Obviously this is one of the first things we want to change for our new cart. Since the main page of our cart is index.php we are going to go looking for the language file at includes/language/english/index.php. Lucky for me and this example the file is there where I would expect to find it.

Before we open up the language file, lets take a look at the code for the main page, the index.php file which resides in the root folder. Inside this file there is a lot of code dealing with displaying new products, etc. But if we scroll down almost to the bottom of the page we find this section of code:

<td class="main"><?php echo tep_customer_greeting(); ?></td>
</tr>
<tr>
<td><?php echo tep_draw_separator('pixel_trans.gif', '100%', '10'); ?></td>
</tr>
<tr>
<td class="main"><?php echo TEXT_MAIN; ?></td>

Now the first line that says

'<?php echo tep_customer_greeting(); ?>'

That calls a function to display the customer greeting, 'Welcome Guest would you like to log yourself in?....' We're not going to cover that at this time, but I wanted to point that out to avoid confusion. What we are looking for here in the last line in the example:

<td class="main"><?php echo TEXT_MAIN; ?></td>

This is where the larger body of the main page text is coming from. Its saying to echo or print to the screen the value of the constant 'TEXT_MAIN'. Ok so now we know what to look for, we can go ahead and open up includes/language/english/index.php. The first define statement in the file looks something like this (It's rather long so I've shortened it for this example):

define('TEXT_MAIN', 'This is a default setup of the osCommerce project, products shown are for demonstrational purposes, <b>any products purchased will not be delivered nor will the customer be billed</b>. Any information seen on these products is to be treated as fictional.........');

You'll likely want to be more creative, but for the sake of example lets assume you want to change the text to read 'You have arrived at my new store'. You probably have the hang of it by now and you should as the change is simple:

define('TEXT_MAIN', 'You have arrived at my new store');

Save the file and upload and you're done, well almost. If your intentions are to keep your site multilingual, you also need to make the corresponding changes in the includes/languages/german/index.php and includes/languages/espanol/index.php files. with the proper translations for those languages.

Finally there is one other thing that falls outside the rule for language files and that is 'buttons'. If we go back to the 'includes/language/english' folder, we can see a sub folder there named 'images' inside the 'images' folder we can find a 'buttons' folder. The whole path goes like this, 'includes/languages/english/images/buttons'. This is where all of the button images are stored which are used for the osCommerce cart. Since the buttons display text, those too are displayed in the selected language. For example button_continue.gif in this folder is the button which displays 'Continue' in English. To make modifications here you'll need to open up Photoshop or another graphics editor, which is beyond the scope of this article but perhaps something we will tackle in the future.

Happy coding!