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 2 00039 00040 #define MAX_TRANSLATE_PARAMS 32 00041 #define CORELANG_ENGLISH 0 00042 00043 /** 00044 * @file ITranslator.h 00045 * @brief Defines interfaces related to translation files. 00046 */ 00047 00048 namespace SourceMod 00049 { 00050 /** 00051 * @brief SourceMod hardcodes the English language (default) to ID 0. 00052 * This cannot be changed and languages.cfg should never have it as anything 00053 * other than the first index. 00054 */ 00055 #define SOURCEMOD_LANGUAGE_ENGLISH 0 00056 00057 /** 00058 * @brief For %T formats, specifies that the language should be that of the 00059 * server and not a specific client. 00060 */ 00061 #define SOURCEMOD_SERVER_LANGUAGE 0 00062 00063 /** 00064 * @brief Translation error codes. 00065 */ 00066 enum TransError 00067 { 00068 Trans_Okay = 0, /**< Translation succeeded. */ 00069 Trans_BadLanguage = 1, /**< Bad language ID. */ 00070 Trans_BadPhrase = 2, /**< Phrase not found. */ 00071 Trans_BadPhraseLanguage = 3, /**< Phrase not found in the given language. */ 00072 Trans_BadPhraseFile = 4, /**< Phrase file was unreadable. */ 00073 }; 00074 00075 /** 00076 * @brief Contains information about a translation phrase. 00077 */ 00078 struct Translation 00079 { 00080 const char *szPhrase; /**< Translated phrase. */ 00081 unsigned int fmt_count; /**< Number of format parameters. */ 00082 int *fmt_order; /**< Array of size fmt_count where each 00083 element is the numerical order of 00084 parameter insertion, starting from 00085 0. 00086 */ 00087 }; 00088 00089 /** 00090 * @brief Represents a phrase file from SourceMod's "translations" folder. 00091 */ 00092 class IPhraseFile 00093 { 00094 public: 00095 /** 00096 * @brief Attempts to find a translation phrase in a phrase file. 00097 * 00098 * @param szPhrase String containing the phrase name. 00099 * @param lang_id Language ID. 00100 * @param pTrans Buffer to store translation info. 00101 * @return Translation error code indicating success 00102 * (pTrans is filled) or failure (pTrans 00103 * contents is undefined). 00104 */ 00105 virtual TransError GetTranslation( 00106 const char *szPhrase, 00107 unsigned int lang_id, 00108 Translation *pTrans) =0; 00109 00110 /** 00111 * @brief Returns the file name of this translation file. 00112 * 00113 * @return File name. 00114 */ 00115 virtual const char *GetFilename() =0; 00116 }; 00117 00118 /** 00119 * Represents a collection of phrase files. 00120 */ 00121 class IPhraseCollection 00122 { 00123 public: 00124 /** 00125 * @brief Adds a phrase file to the collection, using a cached one 00126 * if already found. The return value is provided for informational 00127 * purposes and does not need to be saved. The life time of the 00128 * return pointer is equal to the life time of the collection. 00129 * 00130 * This function will internally ignore dupliate additions but still 00131 * return a valid pointer. 00132 * 00133 * @param filename File name, without the ".txt" extension, of 00134 * the phrase file in the translations folder. 00135 * @return An IPhraseFile pointer, even if the file does 00136 * not exist. 00137 */ 00138 virtual IPhraseFile *AddPhraseFile(const char *filename) =0; 00139 00140 /** 00141 * @brief Returns the number of contained phrase files. 00142 * 00143 * @return Number of contained phrase files. 00144 */ 00145 virtual unsigned int GetFileCount() =0; 00146 00147 /** 00148 * @brief Returns the pointer to a contained phrase file. 00149 * 00150 * @param file File index, from 0 to GetFileCount()-1. 00151 * @return IPhraseFile pointer, or NULL if out of 00152 * range. 00153 */ 00154 virtual IPhraseFile *GetFile(unsigned int file) =0; 00155 00156 /** 00157 * @brief Destroys the phrase collection, freeing all internal 00158 * resources and invalidating the object. 00159 */ 00160 virtual void Destroy() =0; 00161 00162 /** 00163 * @brief Attempts a translation across a given language. All 00164 * contained files are searched for an appropriate match; the 00165 * first valid match is returned. 00166 * 00167 * @param key String containing the phrase name. 00168 * @param langid Language ID to translate to. 00169 * @param pTrans Translation buffer. 00170 * @return Translation error code; on success, 00171 * pTrans is valid. On failure, the 00172 * contents of pTrans is undefined. 00173 */ 00174 virtual TransError FindTranslation( 00175 const char *key, 00176 unsigned int langid, 00177 Translation *pTrans) =0; 00178 00179 /** 00180 * @brief Formats a phrase given a parameter stack. The parameter 00181 * stack size must exactly match the expected parameter count. If 00182 * this count is too small or too large, the format fails. 00183 * 00184 * @param buffer Buffer to store formatted text. 00185 * @param maxlength Maximum length of the buffer. 00186 * @param format String containing format information. 00187 * This is equivalent to SourceMod's Format() 00188 * native, and sub-translations are acceptable. 00189 * @param params An array of pointers to each parameter. 00190 * Integer parameters must have a pointer to the integer. 00191 * Float parameters must have a pointer to a float. 00192 * String parameters must be a string pointer. 00193 * Char parameters must be a pointer to a char. 00194 * Translation parameters fill multiple indexes in the 00195 * array. For %T translations, the expected stack is: 00196 * [phrase string pointer] [int target id pointer] [...] 00197 * Where [...] is the required parameters for the translation, 00198 * in the order expected by the phrase, not the phrase's 00199 * translation. For example, say the format is: 00200 * "%d %T" and the phrase's format is {1:s,2:f}, then the 00201 * parameter stack should be: 00202 * int *, const char *, int *, const char *, float * 00203 * The %t modifier is the same except the target id pointer 00204 * would be removed: 00205 * int *, const char *, const char *, float * 00206 * @param numparams Number of parameters in the params array. 00207 * @param pOutLength Optional pointer filled with output length on success. 00208 * @param pFailPhrase Optional pointer; on failure, is filled with NULL if the 00209 * failure was not due to a failed translation phrase. 00210 * Otherwise, it is filled with the given phrase name pointer 00211 * from the parameter stack. Undefined on success. 00212 * @return True on success. False if the parameter stack was not 00213 * exactly the right length, or if a translation phrase 00214 * could not be found. 00215 */ 00216 virtual bool FormatString( 00217 char *buffer, 00218 size_t maxlength, 00219 const char *format, 00220 void **params, 00221 unsigned int numparams, 00222 size_t *pOutLength, 00223 const char **pFailPhrase) =0; 00224 }; 00225 00226 /** 00227 * @brief Provides functions for translation. 00228 */ 00229 class ITranslator : public SMInterface 00230 { 00231 public: 00232 virtual const char *GetInterfaceName() =0; 00233 virtual unsigned int GetInterfaceVersion() =0; 00234 public: 00235 /** 00236 * @brief Creates a new phrase collection object. 00237 * 00238 * @return A new phrase collection object, which must be 00239 * destroyed via IPhraseCollection::Destroy() when 00240 * no longer needed. 00241 */ 00242 virtual IPhraseCollection *CreatePhraseCollection() =0; 00243 00244 /** 00245 * @brief Returns the server language. 00246 * 00247 * @return Server language index. 00248 */ 00249 virtual unsigned int GetServerLanguage() =0; 00250 00251 /** 00252 * @brief Returns a client's language. 00253 * 00254 * @param client Client index. 00255 * @return Client language index, or server's if client's is 00256 * not known. 00257 */ 00258 virtual unsigned int GetClientLanguage(int client) =0; 00259 00260 /** 00261 * @brief Sets the global client SourceMod will use for assisted 00262 * translations (that is, %t). 00263 * 00264 * @param index Client index (0 for server). 00265 * @return Old global client value. 00266 */ 00267 virtual int SetGlobalTarget(int index) =0; 00268 00269 /** 00270 * @brief Returns the global client SourceMod is currently using 00271 * for assisted translations (that is, %t). 00272 * 00273 * @return Global client index (0 for server). 00274 */ 00275 virtual int GetGlobalTarget() const =0; 00276 00277 /** 00278 * @brief Formats a phrase given a parameter stack. The parameter 00279 * stack size must exactly match the expected parameter count. If 00280 * this count is too small or too large, the format fails. 00281 * 00282 * Note: This is the same as IPhraseCollection::FormatString(), except 00283 * that the IPhraseCollection parameter is explicit instead of implicit. 00284 * 00285 * @param buffer Buffer to store formatted text. 00286 * @param maxlength Maximum length of the buffer. 00287 * @param format String containing format information. 00288 * This is equivalent to SourceMod's Format() 00289 * native, and sub-translations are acceptable. 00290 * @param pPhrases Optional phrase collection pointer to search for 00291 * phrases. 00292 * @param params An array of pointers to each parameter. 00293 * Integer parameters must have a pointer to the integer. 00294 * Float parameters must have a pointer to a float. 00295 * String parameters must be a string pointer. 00296 * Char parameters must be a pointer to a char. 00297 * Translation parameters fill multiple indexes in the 00298 * array. For %T translations, the expected stack is: 00299 * [phrase string pointer] [int target id pointer] [...] 00300 * Where [...] is the required parameters for the translation, 00301 * in the order expected by the phrase, not the phrase's 00302 * translation. For example, say the format is: 00303 * "%d %T" and the phrase's format is {1:s,2:f}, then the 00304 * parameter stack should be: 00305 * int *, const char *, int *, const char *, float * 00306 * The %t modifier is the same except the target id pointer 00307 * would be removed: 00308 * int *, const char *, const char *, float * 00309 * @param numparams Number of parameters in the params array. 00310 * @param pOutLength Optional pointer filled with output length on success. 00311 * @param pFailPhrase Optional pointer; on failure, is filled with NULL if the 00312 * failure was not due to a failed translation phrase. 00313 * Otherwise, it is filled with the given phrase name pointer 00314 * from the parameter stack. Undefined on success. 00315 * @return True on success. False if the parameter stack was not 00316 * exactly the right length, or if a translation phrase 00317 * could not be found. 00318 */ 00319 virtual bool FormatString( 00320 char *buffer, 00321 size_t maxlength, 00322 const char *format, 00323 IPhraseCollection *pPhrases, 00324 void **params, 00325 unsigned int numparams, 00326 size_t *pOutLength, 00327 const char **pFailPhrase) =0; 00328 00329 /** 00330 * @brief Get number of languages. 00331 * 00332 * @return Number of languages. 00333 */ 00334 virtual unsigned int GetLanguageCount() =0; 00335 00336 /** 00337 * @brief Find a language number by name. 00338 * 00339 * @param name Language name. 00340 * @param index Optional pointer to store language index. 00341 * @return True if found, false otherwise. 00342 */ 00343 virtual bool GetLanguageByName(const char *name, unsigned int *index) =0; 00344 }; 00345 } 00346 00347 #endif //_INCLUDE_SOURCEMOD_TRANSLATOR_INTERFACE_H_ 00348
1.7.1