This part of the documentation is not meant for end users of Coppermine, but only for developers. There is no support for this section, it comes as-is.
This document is meant to explain what needs to be done by developers when adding / renaming / deleting files to/from the SVN during development stage.
Refer to the section "Naming Conventions" when adding new files or renaming existing files.
If a developer needs to add a new file to Coppermine's core, here's a list of things that needs to be done:
Adding (user-contributed) language files to the package is a process that needs to be performed in various steps. Those steps don't necessarilly have to be performed by one single developer, but it's advisable that only one dev takes care of a language file contribution to make sure that everything works flawlessly.
- In the channel where the language file has been contributed (usually in a posting on the forum where a user has attached the language file), reply and say that you as a dev team member are volunteering to add the file. This is meant to make sure that the effort is not taken twice.
- Download the file and unarchive it if needed into your testbed
- Start your testbed and force the usage of the new language file by adding the corresponding parameter to the browser's address bar. The testbed should appear in the chosen language. For a basic test it is enough to verify that the language file doesn't break the testbed with an error message or unexpected output.
- Edit the language file with a plain text editor and verify that the header is intact as suggested above. Pay attention to the Coppermine version number that often doesn't match in user-contributed language files.
- Populate the array $lang_translation_info if the translator hasn't done so already. If the translator hasn't supplied a website that he wants to be refered to in the credits section of the docs, refer to the user's profile page of the forum instead.
- Verify that the language file is in unicode (UTF-8 without a BOM) if you can.
- Edit the translator credits of the documentation. In an ideal world you'd be editing all credits files for all documentation languages (docs/language_name/credits.htm and add the credits for the translator there, but of course this get's increasingly harder with a growing number of documentation languages. Therefore, it's acceptable if you just edit the English section of the documentation (docs/en/credits.htm) accordingly and leave the rest to the maintainers of the individual documentation localizations.
- As with all files, you need to edit includes/cpg15x.files.xml as well to reflect the newly added file there.
- Next you need to figure out the status of completion of the language file contribution, i.e. if it's a full translation or only a partial translation. This is a very hard task that might not yield perfect results, so when in doubt, flag a translation as partial translation, which doesn't have an impact in a technical sense, but only serves as an information for end users.
Factors to help you determine if a language file is a full translation or a partial translation can be:
- The contributor may have posted in his forum posting wether his translation has been done partly or fully.
- File size: file sizes for full translations can differ dramatically (as languages that have symbols for words or syllables are less space-consuming than languages that are composed of letters that represent sounds (phonemes to be exact). But with the English language file having roughly 180 KB it's pretty obvious that the language file for British English (lang/english_gb.php) can not be a full translation, but only a partial translation (which is not very surprising, as it contains only the strings where British English differs from American English)
- Cursory reading through the language file in your plain text editor should give you an idea if much of the original, underlying English text shines through, espcially when looking at a language file that is using another character set than latin.
- You will need to make sure that the translation table in Coppermine's database table structure get's updated as well both for fresh installs as well as for updates, that's why you need to
- edit sql/basic.sql, find the lines that start with INSERT INTO CPG_languages and make sure that the language you're adding exists and that the level of completion of the language file matches the database record.
If you're about to add a Klingon language file, search the content of sql/basic.sql for the string klingon. If it's there, i.e. if a line like
If a line that corresponds to the new language's English name doesn't exist, create it (keep the alphabetical structure of the INSERT INTO CPG_languages-section in mind) accordingly.
exists, just edit the fields that determine if the translation exists and wether it's complete (full translation) or not.
For details, refer to the language manager documentation.
- edit sql/update.sql with a plain text editor.
- If the line in sql/basic.sql that corresponds to the new language file didn't exist, you will need to add a line to sql/update.sql that adds a new record.
For the above mentioned Klingon language file, the line to create a new database record would be
- If there has been a database record already for the language file and you just need to toggle it from unavailable to available, add a line that performs the update
The example for Klingon in this case would be
- Make sure that there is a flag image inside the folder images/flags/ that represents the new language. If there is no flag available, create one if you have the skills to do so and add that file. Alternatively, assign a blank image as a flag as a temporary workaround.
- Add the new language file in your SVN client to the repository. You will need write access to the subversion repository in order to accomplish this.
- Add a line to the change log that corresponds to the new language file.
- Test the language file as thoroughly as you can on your local testbed: browse the gallery as guest, registered user and admin, try to upload a file, take a look at the main views (index, thumbnail page, intermediate image).
- Commit your changes to the subversion repository using your subversion client.
- Finally reply to the thread where the user has contributed the language file, posting that you have done what you did. It might help to add a reference to the web SVN and post the revision of your commit.
- If you have admin privileges on the Coppermine forum, change the language file contributor's group membership; make him member of the translator group.
- If you have access to the Coppermine internet site, edit the credits file there as well to reflect the newly added translator.
If a file name can not be kept (e.g. because of collision with naming conventions), it should be renamed instead of deleting the old one and creating a new one. The benfit of renaming is the fact that the version history will be kept in the Subversion repository.
Once a file has been renamed in SVN, you will have to make additional edits:
- Add an entry for your the new file name in includes/cpg15x.files.xml. Details can be found in the section Versioncheck : XML structure
- If the old file name already has gone into a prvious public release, you need to make sure that end users will not have an outdated, leftover copy of the file with the old name when performing an update. To accomplish this, you should edit update.php, find the definition of the array $delete_file_array and add the old file name to it.
Additionally, you should edit includes/cpg15x.files.xml and flag the old name with the status "remove".
- If the old file name has not gone into a previous release, it's enough to edit includes/cpg15x.files.xml and just remove the record that refers to the old file name.
- You have to search through all files (both PHP files as well as HTML files inside the documentation) for references to the old file name and change the references as well.
In a nutshell: what has been said above about renaming files applies to deleting files as well: after having deleted the file in SVN, make sure to edit the XML file used for versioncheck and the array of files scheduled for deleting by the updater.
Keep in mind though that before deleting core PHP files, you should discuss this with your fellow devs first on the dev-only board.