Language Nuance for Testplugin Templates.

The testplugin templates provides a set of templates which manages all the plugin basic tasks, including generation of tarballs and metadata.

This documentation is a WIP. Current parts:

FIXME: This is moved from languages: it’s specific for the testplugin setup, but certainly don’t belong here.

PlugIn usage of own catalog for Language "strings"

wxWidgets provide a macro to help with the translation of strings into the local language. This is done using the macro, normally seen as _("string") in the code. At compile time this is translated to wxTranslation("string") which at runtime will return the string "string" translated into the local language. The translation is done by matching the string "string" in the language catalog set (all the catalogs that have been loaded for OCPN). The first match that is found is returned.

It is possible for each plugin to use the same words for different meanings, eg. "Port" can mean "Communications Port", "Harbor", "Port of Entry", "Port Side", "Porthole", etc. Unfortunately as the first instance of the word is returned the translation may not be appropriate. The upside of this is if you use strings that have not been translated in your catalog, then it may have been in another and this translation will be returned. The downside is that you cannot specify, using wxWidgets macro, which catalog to use.

The wxTranslation method comes in two flavors wxTranslation("string")
wxTranslation("string", "catalog") You could use this in your code, but it would be long winded. It is possible to redefine the macro such that it will use the second form if "catalog" is specified. The following shows how this can be done to allow the code to maintain the look of all the other code in OCPN and the PlugIns.

Changes to CMake file

If you use Pavel’s/Sean’s PlugIn cmake file set you will have a file called PluginConfigure.cmake in the "cmake" directory of your project. This file needs a new line adding:
configure_file(cmake/wxWTranslateCatalog.h.in ${PROJECT_SOURCE_DIR}/include/wxWTranslateCatalog.h)
This line is added after the line:
configure_file(cmake/version.h.in ${PROJECT_SOURCE_DIR}/include/version.h)

New template file

The name of the input template file and the output header file can be changed. The name was picked to signify "wxWidgets Translate with Catalog".
The content of the input template file is:

'' ******************************************************************************
 * $Id: wxWtranslateCatalog.h,v 1.0 2015/01/28 01:54:37 Jon Gough Exp $
 *
 * Project:  OpenCPN
 * Purpose:  Redefine _() macro to allow usage of catalog
 * Author:   Jon Gough
 *
 ***************************************************************************
 *   Copyright (C) 2010 by David S. Register   *
 *   $EMAIL$                                                               *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the                         *
 *   Free Software Foundation, Inc.,                                       *
 *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,  USA.         *
 ***************************************************************************
 */
#ifndef _ODCATTRANS_H_
#define _ODCATTRANS_H_

#ifndef WXINTL_NO_GETTEXT_MACRO
#ifdef _
#undef _
#endif // _
#if wxCHECK_VERSION(3,0,0)
#define _(s) wxGetTranslation((s), wxS(__GESHI_QUOT__opencpn-${PROJECT_NAME}__GESHI_QUOT__))
#else // wxCHECK_VERSION(3,0,0)
    #define _(s) wxGetTranslation(wxT(s), wxT("opencpn-${PROJECT_NAME}"))
#endif // wxCHECK_VERSION(3,0,0)
#endif // WXINTL_NO_GETTEXT_MACRO

#endif
''

This will generate a header file in the include directory that has the following content:

''/******************************************************************************
 * $Id: wxWTranslateCatalog.h,v 1.0 2015/01/28 01:54:37 Jon Gough Exp $
 *
 * Project:  OpenCPN
 * Purpose:  Redefine _() macro to allow usage of catalog
 * Author:   Jon Gough
 *
 ***************************************************************************
 *   Copyright (C) 2010 by David S. Register   *
 *   $EMAIL$                                                               *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the                         *
 *   Free Software Foundation, Inc.,                                       *
 *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,  USA.         *
 ***************************************************************************
 */
#ifndef _ODCATTRANS_H_
#define _ODCATTRANS_H_

#ifndef WXINTL_NO_GETTEXT_MACRO
#ifdef _
#undef _
#endif // _
#define _(s) wxGetTranslation((s), wxS(__GESHI_QUOT__opencpn-your_plugin_pi__GESHI_QUOT__))
#else // wxCHECK_VERSION(3,0,0)
    #define _(s) wxGetTranslation(wxT(s), wxT("opencpn-your_plugin_pi"))
#endif // wxCHECK_VERSION(3,0,0)
#endif // WXINTL_NO_GETTEXT_MACRO

#endif
''

This header needs to be included in every source module that is going to do translations. It should be placed after the wxWidgets includes to ensure that it can redefine the macro.

Changed template file

The "version.h.in" used by this cmake process also needs to be updated with two new lines:

#define PLUGIN_NAME ${PROJECT_NAME}

#define PLUGIN_CATALOG_NAME wxS("opencpn-${PROJECT_NAME}")

The whole "version.h.in" file should look like:

#define PLUGIN_NAME ${PROJECT_NAME}

#define PLUGIN_CATALOG_NAME wxS("opencpn-${PROJECT_NAME}")

#define PLUGIN_VERSION_MAJOR ${VERSION_MAJOR}

#define PLUGIN_VERSION_MINOR ${VERSION_MINOR}

#define PLUGIN_VERSION_PATCH ${VERSION_PATCH}

#define PLUGIN_VERSION_DATE "{VERSION_DATE}"

Change to main module

To implement this the code you use to set the locale catalog needs to change from:

AddLocaleCatalog( opencpn-your_plugin-name_pi );

to:

AddLocaleCatalog( PLUGIN_CATALOG_NAME );

The "PLUGIN_CATALOG_NAME" is translated at compile time to the correct name for your plugin. This ensures that you are using the same catalog as that added to OpenCPN. This is really a failsafe.

How to make wxFormBuilder use new wxWTranslateCatalog.h file

This is quite simple. Once you have created the wxWTranslateCatalog.h file you can include it in all generated header files by a single change to the project file.
Open wxFormBuilder with the project file you want to change, then go to Properties/C++ Properties/class_decoration/header and enter wxWTranslateCatalog.h in that field. This will append this header file after all the wxWidgets headers and allow it to redefine the "_()" macro to use the project local catalog. Now there is no need to change the generated file to make it work.

Analysis and Avoidance of Duplicate Language "strings" (words or phrases)

Proposed by NAV.

More important is probably the simple procedure I used to make it (ready in a few minutes):
1. Go to GITHUB;
2. Find the correct repository (master branch);
3. Open po-file of the language you’re interested in;
4. Click on "Raw";
5. Copy all;
6. Paste to two different sheets (e.g. 1 and 2) of Excel;
7. Delete all empty rows on sheet 1 (use Excel Add On to do this with a few mouse clicks);
8. Filter on "msgid" in sheet 1;
9. Delete all hidden rows on sheet 1 (use Excel Add On to do this with a few mouse clicks);
10. Delete all empty rows on sheet 2;
11. Filter on "msgstr" in sheet 2;
12. Delete all hidden rows on sheet 2;
13. Copy all msgstr rows from sheet 2 to next empty column in sheet 1;
14. Check results.
15. Add plugin name in separate column for all copied rows;
16. Add sequential number in separate column to be able to re-sort.

The Excel Add On I use adds additional functionality, of which I only used two for this procedure. You can find it here: ASAP Utilities