dvander@2042: /**
dvander@2042: * vim: set ts=4 :
dvander@2042: * =============================================================================
dvander@2042: * SourceMod
dvander@2042: * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved.
dvander@2042: * =============================================================================
dvander@2042: *
dvander@2042: * This program is free software; you can redistribute it and/or modify it under
dvander@2042: * the terms of the GNU General Public License, version 3.0, as published by the
dvander@2042: * Free Software Foundation.
dvander@2042: *
dvander@2042: * This program is distributed in the hope that it will be useful, but WITHOUT
dvander@2042: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
dvander@2042: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
dvander@2042: * details.
dvander@2042: *
dvander@2042: * You should have received a copy of the GNU General Public License along with
dvander@2042: * this program. If not, see .
dvander@2042: *
dvander@2042: * As a special exception, AlliedModders LLC gives you permission to link the
dvander@2042: * code of this program (as well as its derivative works) to "Half-Life 2," the
dvander@2042: * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
dvander@2042: * by the Valve Corporation. You must obey the GNU General Public License in
dvander@2042: * all respects for all other code used. Additionally, AlliedModders LLC grants
dvander@2042: * this exception to all derivative works. AlliedModders LLC defines further
dvander@2042: * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
dvander@2042: * or .
dvander@2042: *
dvander@2042: * Version: $Id$
dvander@2042: */
dvander@2042:
dvander@2042: #ifndef _INCLUDE_SOURCEMOD_TRANSLATOR_INTERFACE_H_
dvander@2042: #define _INCLUDE_SOURCEMOD_TRANSLATOR_INTERFACE_H_
dvander@2042:
dvander@2042: #include
dvander@2042:
dvander@2042: #define SMINTERFACE_TRANSLATOR_NAME "ITranslator"
dvander@2042: #define SMINTERFACE_TRANSLATOR_VERSION 1
dvander@2042:
dvander@2042: /**
dvander@2042: * @file ITranslator.h
dvander@2042: * @brief Defines interfaces related to translation files.
dvander@2042: */
dvander@2042:
dvander@2042: namespace SourceMod
dvander@2042: {
dvander@2042: /**
dvander@2042: * @brief SourceMod hardcodes the English language (default) to ID 0.
dvander@2042: * This cannot be changed and languages.cfg should never have it as anything
dvander@2042: * other than the first index.
dvander@2042: */
dvander@2042: #define SOURCEMOD_LANGUAGE_ENGLISH 0
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief For %T formats, specifies that the language should be that of the
dvander@2042: * server and not a specific client.
dvander@2042: */
dvander@2042: #define SOURCEMOD_SERVER_LANGUAGE 0
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Translation error codes.
dvander@2042: */
dvander@2042: enum TransError
dvander@2042: {
dvander@2042: Trans_Okay = 0, /**< Translation succeeded. */
dvander@2042: Trans_BadLanguage = 1, /**< Bad language ID. */
dvander@2042: Trans_BadPhrase = 2, /**< Phrase not found. */
dvander@2042: Trans_BadPhraseLanguage = 3, /**< Phrase not found in the given language. */
dvander@2042: Trans_BadPhraseFile = 4, /**< Phrase file was unreadable. */
dvander@2042: };
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Contains information about a translation phrase.
dvander@2042: */
dvander@2042: struct Translation
dvander@2042: {
dvander@2042: const char *szPhrase; /**< Translated phrase. */
dvander@2042: unsigned int fmt_count; /**< Number of format parameters. */
dvander@2042: int *fmt_order; /**< Array of size fmt_count where each
dvander@2042: element is the numerical order of
dvander@2042: parameter insertion, starting from
dvander@2042: 0.
dvander@2042: */
dvander@2042: };
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Represents a phrase file from SourceMod's "translations" folder.
dvander@2042: */
dvander@2042: class IPhraseFile
dvander@2042: {
dvander@2042: public:
dvander@2042: /**
dvander@2042: * @brief Attempts to find a translation phrase in a phrase file.
dvander@2042: *
dvander@2042: * @param szPhrase String containing the phrase name.
dvander@2042: * @param lang_id Language ID.
dvander@2042: * @param pTrans Buffer to store translation info.
dvander@2042: * @return Translation error code indicating success
dvander@2042: * (pTrans is filled) or failure (pTrans
dvander@2042: * contents is undefined).
dvander@2042: */
dvander@2042: virtual TransError GetTranslation(
dvander@2042: const char *szPhrase,
dvander@2042: unsigned int lang_id,
dvander@2042: Translation *pTrans) =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Returns the file name of this translation file.
dvander@2042: *
dvander@2042: * @return File name.
dvander@2042: */
dvander@2042: virtual const char *GetFilename() =0;
dvander@2042: };
dvander@2042:
dvander@2042: /**
dvander@2042: * Represents a collection of phrase files.
dvander@2042: */
dvander@2042: class IPhraseCollection
dvander@2042: {
dvander@2042: public:
dvander@2042: /**
dvander@2042: * @brief Adds a phrase file to the collection, using a cached one
dvander@2042: * if already found. The return value is provided for informational
dvander@2042: * purposes and does not need to be saved. The life time of the
dvander@2042: * return pointer is equal to the life time of the collection.
dvander@2042: *
dvander@2042: * This function will internally ignore dupliate additions but still
dvander@2042: * return a valid pointer.
dvander@2042: *
dvander@2042: * @param filename File name, without the ".txt" extension, of
dvander@2042: * the phrase file in the translations folder.
dvander@2042: * @return An IPhraseFile pointer, even if the file does
dvander@2042: * not exist.
dvander@2042: */
dvander@2042: virtual IPhraseFile *AddPhraseFile(const char *filename) =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Returns the number of contained phrase files.
dvander@2042: *
dvander@2042: * @return Number of contained phrase files.
dvander@2042: */
dvander@2042: virtual unsigned int GetFileCount() =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Returns the pointer to a contained phrase file.
dvander@2042: *
dvander@2042: * @param file File index, from 0 to GetFileCount()-1.
dvander@2042: * @return IPhraseFile pointer, or NULL if out of
dvander@2042: * range.
dvander@2042: */
dvander@2042: virtual IPhraseFile *GetFile(unsigned int file) =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Destroys the phrase collection, freeing all internal
dvander@2042: * resources and invalidating the object.
dvander@2042: */
dvander@2042: virtual void Destroy() =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Attempts a translation across a given language. All
dvander@2042: * contained files are searched for an appropriate match; the
dvander@2042: * first valid match is returned.
dvander@2042: *
dvander@2042: * @param key String containing the phrase name.
dvander@2042: * @param langid Language ID to translate to.
dvander@2042: * @param pTrans Translation buffer.
dvander@2042: * @return Translation error code; on success,
dvander@2042: * pTrans is valid. On failure, the
dvander@2042: * contents of pTrans is undefined.
dvander@2042: */
dvander@2042: virtual TransError FindTranslation(
dvander@2042: const char *key,
dvander@2042: unsigned int langid,
dvander@2042: Translation *pTrans) =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Formats a phrase given a parameter stack. The parameter
dvander@2042: * stack size must exactly match the expected parameter count. If
dvander@2042: * this count is too small or too large, the format fails.
dvander@2042: *
dvander@2042: * @param buffer Buffer to store formatted text.
dvander@2042: * @param maxlength Maximum length of the buffer.
dvander@2042: * @param format String containing format information.
dvander@2042: * This is equivalent to SourceMod's Format()
dvander@2042: * native, and sub-translations are acceptable.
dvander@2042: * @param params An array of pointers to each parameter.
dvander@2042: * Integer parameters must have a pointer to the integer.
dvander@2042: * Float parameters must have a pointer to a float.
dvander@2042: * String parameters must be a string pointer.
dvander@2042: * Char parameters must be a pointer to a char.
dvander@2042: * Translation parameters fill multiple indexes in the
dvander@2042: * array. For %T translations, the expected stack is:
dvander@2042: * [phrase string pointer] [int target id pointer] [...]
dvander@2042: * Where [...] is the required parameters for the translation,
dvander@2042: * in the order expected by the phrase, not the phrase's
dvander@2042: * translation. For example, say the format is:
dvander@2042: * "%d %T" and the phrase's format is {1:s,2:f}, then the
dvander@2042: * parameter stack should be:
dvander@2042: * int *, const char *, int *, const char *, float *
dvander@2042: * The %t modifier is the same except the target id pointer
dvander@2042: * would be removed:
dvander@2042: * int *, const char *, const char *, float *
dvander@2042: * @param numparams Number of parameters in the params array.
dvander@2042: * @param pOutLength Optional pointer filled with output length on success.
dvander@2042: * @param pFailPhrase Optional pointer; on failure, is filled with NULL if the
dvander@2042: * failure was not due to a failed translation phrase.
dvander@2042: * Otherwise, it is filled with the given phrase name pointer
dvander@2042: * from the parameter stack. Undefined on success.
dvander@2042: * @return True on success. False if the parameter stack was not
dvander@2042: * exactly the right length, or if a translation phrase
dvander@2042: * could not be found.
dvander@2042: */
dvander@2042: virtual bool FormatString(
dvander@2042: char *buffer,
dvander@2042: size_t maxlength,
dvander@2042: const char *format,
dvander@2042: void **params,
dvander@2042: unsigned int numparams,
dvander@2042: size_t *pOutLength,
dvander@2042: const char **pFailPhrase) =0;
dvander@2042: };
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Provides functions for translation.
dvander@2042: */
dvander@2042: class ITranslator : public SMInterface
dvander@2042: {
dvander@2042: public:
dvander@2042: virtual const char *GetInterfaceName() =0;
dvander@2042: virtual unsigned int GetInterfaceVersion() =0;
dvander@2042: public:
dvander@2042: /**
dvander@2042: * @brief Creates a new phrase collection object.
dvander@2042: *
dvander@2042: * @return A new phrase collection object, which must be
dvander@2042: * destroyed via IPhraseCollection::Destroy() when
dvander@2042: * no longer needed.
dvander@2042: */
dvander@2042: virtual IPhraseCollection *CreatePhraseCollection() =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Returns the server language.
dvander@2042: *
dvander@2042: * @return Server language index.
dvander@2042: */
dvander@2042: virtual unsigned int GetServerLanguage() =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Returns a client's language.
dvander@2042: *
dvander@2042: * @param client Client index.
dvander@2042: * @return Client language index, or server's if client's is
dvander@2042: * not known.
dvander@2042: */
dvander@2042: virtual unsigned int GetClientLanguage(int client) =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Sets the global client SourceMod will use for assisted
dvander@2042: * translations (that is, %t).
dvander@2042: *
dvander@2042: * @param index Client index (0 for server).
dvander@2042: * @return Old global client value.
dvander@2042: */
dvander@2042: virtual int SetGlobalTarget(int index) =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Returns the global client SourceMod is currently using
dvander@2042: * for assisted translations (that is, %t).
dvander@2042: *
dvander@2042: * @return Global client index (0 for server).
dvander@2042: */
dvander@2042: virtual int GetGlobalTarget() const =0;
dvander@2042:
dvander@2042: /**
dvander@2042: * @brief Formats a phrase given a parameter stack. The parameter
dvander@2042: * stack size must exactly match the expected parameter count. If
dvander@2042: * this count is too small or too large, the format fails.
dvander@2042: *
dvander@2042: * Note: This is the same as IPhraseCollection::FormatString(), except
dvander@2042: * that the IPhraseCollection parameter is explicit instead of implicit.
dvander@2042: *
dvander@2042: * @param buffer Buffer to store formatted text.
dvander@2042: * @param maxlength Maximum length of the buffer.
dvander@2042: * @param format String containing format information.
dvander@2042: * This is equivalent to SourceMod's Format()
dvander@2042: * native, and sub-translations are acceptable.
dvander@2042: * @param pPhrases Optional phrase collection pointer to search for
dvander@2042: * phrases.
dvander@2042: * @param params An array of pointers to each parameter.
dvander@2042: * Integer parameters must have a pointer to the integer.
dvander@2042: * Float parameters must have a pointer to a float.
dvander@2042: * String parameters must be a string pointer.
dvander@2042: * Char parameters must be a pointer to a char.
dvander@2042: * Translation parameters fill multiple indexes in the
dvander@2042: * array. For %T translations, the expected stack is:
dvander@2042: * [phrase string pointer] [int target id pointer] [...]
dvander@2042: * Where [...] is the required parameters for the translation,
dvander@2042: * in the order expected by the phrase, not the phrase's
dvander@2042: * translation. For example, say the format is:
dvander@2042: * "%d %T" and the phrase's format is {1:s,2:f}, then the
dvander@2042: * parameter stack should be:
dvander@2042: * int *, const char *, int *, const char *, float *
dvander@2042: * The %t modifier is the same except the target id pointer
dvander@2042: * would be removed:
dvander@2042: * int *, const char *, const char *, float *
dvander@2042: * @param numparams Number of parameters in the params array.
dvander@2042: * @param pOutLength Optional pointer filled with output length on success.
dvander@2042: * @param pFailPhrase Optional pointer; on failure, is filled with NULL if the
dvander@2042: * failure was not due to a failed translation phrase.
dvander@2042: * Otherwise, it is filled with the given phrase name pointer
dvander@2042: * from the parameter stack. Undefined on success.
dvander@2042: * @return True on success. False if the parameter stack was not
dvander@2042: * exactly the right length, or if a translation phrase
dvander@2042: * could not be found.
dvander@2042: */
dvander@2042: virtual bool FormatString(
dvander@2042: char *buffer,
dvander@2042: size_t maxlength,
dvander@2042: const char *format,
dvander@2042: IPhraseCollection *pPhrases,
dvander@2042: void **params,
dvander@2042: unsigned int numparams,
dvander@2042: size_t *pOutLength,
dvander@2042: const char **pFailPhrase) =0;
dvander@2042: };
dvander@2042: }
dvander@2042:
dvander@2042: #endif //_INCLUDE_SOURCEMOD_TRANSLATOR_INTERFACE_H_
dvander@2042: