00001 /** 00002 * vim: set ts=4 : 00003 * ============================================================================= 00004 * SourceMod 00005 * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved. 00006 * ============================================================================= 00007 * 00008 * This program is free software; you can redistribute it and/or modify it under 00009 * the terms of the GNU General Public License, version 3.0, as published by the 00010 * Free Software Foundation. 00011 * 00012 * This program is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00014 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 00015 * details. 00016 * 00017 * You should have received a copy of the GNU General Public License along with 00018 * this program. If not, see <http://www.gnu.org/licenses/>. 00019 * 00020 * As a special exception, AlliedModders LLC gives you permission to link the 00021 * code of this program (as well as its derivative works) to "Half-Life 2," the 00022 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software 00023 * by the Valve Corporation. You must obey the GNU General Public License in 00024 * all respects for all other code used. Additionally, AlliedModders LLC grants 00025 * this exception to all derivative works. AlliedModders LLC defines further 00026 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007), 00027 * or <http://www.sourcemod.net/license.php>. 00028 * 00029 * Version: $Id$ 00030 */ 00031 00032 #ifndef _INCLUDE_SOURCEMOD_TRANSLATOR_INTERFACE_H_ 00033 #define _INCLUDE_SOURCEMOD_TRANSLATOR_INTERFACE_H_ 00034 00035 #include <IShareSys.h> 00036 00037 #define SMINTERFACE_TRANSLATOR_NAME "ITranslator" 00038 #define SMINTERFACE_TRANSLATOR_VERSION 1 00039 00040 /** 00041 * @file ITranslator.h 00042 * @brief Defines interfaces related to translation files. 00043 */ 00044 00045 namespace SourceMod 00046 { 00047 /** 00048 * @brief SourceMod hardcodes the English language (default) to ID 0. 00049 * This cannot be changed and languages.cfg should never have it as anything 00050 * other than the first index. 00051 */ 00052 #define SOURCEMOD_LANGUAGE_ENGLISH 0 00053 00054 /** 00055 * @brief For %T formats, specifies that the language should be that of the 00056 * server and not a specific client. 00057 */ 00058 #define SOURCEMOD_SERVER_LANGUAGE 0 00059 00060 /** 00061 * @brief Translation error codes. 00062 */ 00063 enum TransError 00064 { 00065 Trans_Okay = 0, /**< Translation succeeded. */ 00066 Trans_BadLanguage = 1, /**< Bad language ID. */ 00067 Trans_BadPhrase = 2, /**< Phrase not found. */ 00068 Trans_BadPhraseLanguage = 3, /**< Phrase not found in the given language. */ 00069 Trans_BadPhraseFile = 4, /**< Phrase file was unreadable. */ 00070 }; 00071 00072 /** 00073 * @brief Contains information about a translation phrase. 00074 */ 00075 struct Translation 00076 { 00077 const char *szPhrase; /**< Translated phrase. */ 00078 unsigned int fmt_count; /**< Number of format parameters. */ 00079 int *fmt_order; /**< Array of size fmt_count where each 00080 element is the numerical order of 00081 parameter insertion, starting from 00082 0. 00083 */ 00084 }; 00085 00086 /** 00087 * @brief Represents a phrase file from SourceMod's "translations" folder. 00088 */ 00089 class IPhraseFile 00090 { 00091 public: 00092 /** 00093 * @brief Attempts to find a translation phrase in a phrase file. 00094 * 00095 * @param szPhrase String containing the phrase name. 00096 * @param lang_id Language ID. 00097 * @param pTrans Buffer to store translation info. 00098 * @return Translation error code indicating success 00099 * (pTrans is filled) or failure (pTrans 00100 * contents is undefined). 00101 */ 00102 virtual TransError GetTranslation( 00103 const char *szPhrase, 00104 unsigned int lang_id, 00105 Translation *pTrans) =0; 00106 00107 /** 00108 * @brief Returns the file name of this translation file. 00109 * 00110 * @return File name. 00111 */ 00112 virtual const char *GetFilename() =0; 00113 }; 00114 00115 /** 00116 * Represents a collection of phrase files. 00117 */ 00118 class IPhraseCollection 00119 { 00120 public: 00121 /** 00122 * @brief Adds a phrase file to the collection, using a cached one 00123 * if already found. The return value is provided for informational 00124 * purposes and does not need to be saved. The life time of the 00125 * return pointer is equal to the life time of the collection. 00126 * 00127 * This function will internally ignore dupliate additions but still 00128 * return a valid pointer. 00129 * 00130 * @param filename File name, without the ".txt" extension, of 00131 * the phrase file in the translations folder. 00132 * @return An IPhraseFile pointer, even if the file does 00133 * not exist. 00134 */ 00135 virtual IPhraseFile *AddPhraseFile(const char *filename) =0; 00136 00137 /** 00138 * @brief Returns the number of contained phrase files. 00139 * 00140 * @return Number of contained phrase files. 00141 */ 00142 virtual unsigned int GetFileCount() =0; 00143 00144 /** 00145 * @brief Returns the pointer to a contained phrase file. 00146 * 00147 * @param file File index, from 0 to GetFileCount()-1. 00148 * @return IPhraseFile pointer, or NULL if out of 00149 * range. 00150 */ 00151 virtual IPhraseFile *GetFile(unsigned int file) =0; 00152 00153 /** 00154 * @brief Destroys the phrase collection, freeing all internal 00155 * resources and invalidating the object. 00156 */ 00157 virtual void Destroy() =0; 00158 00159 /** 00160 * @brief Attempts a translation across a given language. All 00161 * contained files are searched for an appropriate match; the 00162 * first valid match is returned. 00163 * 00164 * @param key String containing the phrase name. 00165 * @param langid Language ID to translate to. 00166 * @param pTrans Translation buffer. 00167 * @return Translation error code; on success, 00168 * pTrans is valid. On failure, the 00169 * contents of pTrans is undefined. 00170 */ 00171 virtual TransError FindTranslation( 00172 const char *key, 00173 unsigned int langid, 00174 Translation *pTrans) =0; 00175 00176 /** 00177 * @brief Formats a phrase given a parameter stack. The parameter 00178 * stack size must exactly match the expected parameter count. If 00179 * this count is too small or too large, the format fails. 00180 * 00181 * @param buffer Buffer to store formatted text. 00182 * @param maxlength Maximum length of the buffer. 00183 * @param format String containing format information. 00184 * This is equivalent to SourceMod's Format() 00185 * native, and sub-translations are acceptable. 00186 * @param params An array of pointers to each parameter. 00187 * Integer parameters must have a pointer to the integer. 00188 * Float parameters must have a pointer to a float. 00189 * String parameters must be a string pointer. 00190 * Char parameters must be a pointer to a char. 00191 * Translation parameters fill multiple indexes in the 00192 * array. For %T translations, the expected stack is: 00193 * [phrase string pointer] [int target id pointer] [...] 00194 * Where [...] is the required parameters for the translation, 00195 * in the order expected by the phrase, not the phrase's 00196 * translation. For example, say the format is: 00197 * "%d %T" and the phrase's format is {1:s,2:f}, then the 00198 * parameter stack should be: 00199 * int *, const char *, int *, const char *, float * 00200 * The %t modifier is the same except the target id pointer 00201 * would be removed: 00202 * int *, const char *, const char *, float * 00203 * @param numparams Number of parameters in the params array. 00204 * @param pOutLength Optional pointer filled with output length on success. 00205 * @param pFailPhrase Optional pointer; on failure, is filled with NULL if the 00206 * failure was not due to a failed translation phrase. 00207 * Otherwise, it is filled with the given phrase name pointer 00208 * from the parameter stack. Undefined on success. 00209 * @return True on success. False if the parameter stack was not 00210 * exactly the right length, or if a translation phrase 00211 * could not be found. 00212 */ 00213 virtual bool FormatString( 00214 char *buffer, 00215 size_t maxlength, 00216 const char *format, 00217 void **params, 00218 unsigned int numparams, 00219 size_t *pOutLength, 00220 const char **pFailPhrase) =0; 00221 }; 00222 00223 /** 00224 * @brief Provides functions for translation. 00225 */ 00226 class ITranslator : public SMInterface 00227 { 00228 public: 00229 virtual const char *GetInterfaceName() =0; 00230 virtual unsigned int GetInterfaceVersion() =0; 00231 public: 00232 /** 00233 * @brief Creates a new phrase collection object. 00234 * 00235 * @return A new phrase collection object, which must be 00236 * destroyed via IPhraseCollection::Destroy() when 00237 * no longer needed. 00238 */ 00239 virtual IPhraseCollection *CreatePhraseCollection() =0; 00240 00241 /** 00242 * @brief Returns the server language. 00243 * 00244 * @return Server language index. 00245 */ 00246 virtual unsigned int GetServerLanguage() =0; 00247 00248 /** 00249 * @brief Returns a client's language. 00250 * 00251 * @param client Client index. 00252 * @return Client language index, or server's if client's is 00253 * not known. 00254 */ 00255 virtual unsigned int GetClientLanguage(int client) =0; 00256 00257 /** 00258 * @brief Sets the global client SourceMod will use for assisted 00259 * translations (that is, %t). 00260 * 00261 * @param index Client index (0 for server). 00262 * @return Old global client value. 00263 */ 00264 virtual int SetGlobalTarget(int index) =0; 00265 00266 /** 00267 * @brief Returns the global client SourceMod is currently using 00268 * for assisted translations (that is, %t). 00269 * 00270 * @return Global client index (0 for server). 00271 */ 00272 virtual int GetGlobalTarget() const =0; 00273 00274 /** 00275 * @brief Formats a phrase given a parameter stack. The parameter 00276 * stack size must exactly match the expected parameter count. If 00277 * this count is too small or too large, the format fails. 00278 * 00279 * Note: This is the same as IPhraseCollection::FormatString(), except 00280 * that the IPhraseCollection parameter is explicit instead of implicit. 00281 * 00282 * @param buffer Buffer to store formatted text. 00283 * @param maxlength Maximum length of the buffer. 00284 * @param format String containing format information. 00285 * This is equivalent to SourceMod's Format() 00286 * native, and sub-translations are acceptable. 00287 * @param pPhrases Optional phrase collection pointer to search for 00288 * phrases. 00289 * @param params An array of pointers to each parameter. 00290 * Integer parameters must have a pointer to the integer. 00291 * Float parameters must have a pointer to a float. 00292 * String parameters must be a string pointer. 00293 * Char parameters must be a pointer to a char. 00294 * Translation parameters fill multiple indexes in the 00295 * array. For %T translations, the expected stack is: 00296 * [phrase string pointer] [int target id pointer] [...] 00297 * Where [...] is the required parameters for the translation, 00298 * in the order expected by the phrase, not the phrase's 00299 * translation. For example, say the format is: 00300 * "%d %T" and the phrase's format is {1:s,2:f}, then the 00301 * parameter stack should be: 00302 * int *, const char *, int *, const char *, float * 00303 * The %t modifier is the same except the target id pointer 00304 * would be removed: 00305 * int *, const char *, const char *, float * 00306 * @param numparams Number of parameters in the params array. 00307 * @param pOutLength Optional pointer filled with output length on success. 00308 * @param pFailPhrase Optional pointer; on failure, is filled with NULL if the 00309 * failure was not due to a failed translation phrase. 00310 * Otherwise, it is filled with the given phrase name pointer 00311 * from the parameter stack. Undefined on success. 00312 * @return True on success. False if the parameter stack was not 00313 * exactly the right length, or if a translation phrase 00314 * could not be found. 00315 */ 00316 virtual bool FormatString( 00317 char *buffer, 00318 size_t maxlength, 00319 const char *format, 00320 IPhraseCollection *pPhrases, 00321 void **params, 00322 unsigned int numparams, 00323 size_t *pOutLength, 00324 const char **pFailPhrase) =0; 00325 }; 00326 } 00327 00328 #endif //_INCLUDE_SOURCEMOD_TRANSLATOR_INTERFACE_H_ 00329
1.5.1