Localization Support

[MohabCodeX]

✅ tasks

• fix tinygettext for mac/linux.
• add global translation support.
• set/getCurrentTranslationLanguage maybe need to be compatible with getLocalization.
• overview documentation.

This PR adds localization support for MTA resources using .po files. Resources can include translation files directly in their meta.xml and use functions to get translated text.

Addresses Issue

Resolves the localization framework request in [mtasa-resources#361] (Thanks to jlillis for the suggestion), enabling multi-language support instead of a single language.

Features

• Add <translation src="locales/en.po" primary="true" /> tags in meta.xml
• Fallback to primary language, then first imported language when translations are missing

New Functions

Server-Side:

• getTranslation(msgid [, lang]) → string
• getAvailableTranslations() → table

Client-Side:

• getTranslation(msgid [, lang]) → string
• getCurrentTranslationLanguage() → string
• setCurrentTranslationLanguage(lang) → boolean
• getAvailableTranslations() → table

How it works

Resources place .po files in a locales/ folder (or any folder inside the resource) and declare them in meta.xml. The system loads translations on resource start. Missing translations fallback to the primary language, then to the first imported language, or finally the original message ID. The primary language is set with primary="true"; otherwise, the first translation file becomes the primary.

Details

• Built on MTA's existing tinygettext library
• Separate dictionaries prevent language data corruption
• Zero network overhead; translations cached locally on both client and server

Testing

test_localization.zip

Additional translation functions will be added in future updates to expand functionality.

[samr46]

Great job! This solution should be more efficient than Lua based options.

I'm wondering if it's feasible to add this functionality on client level (so translations could be shared across all resources). This way complex projects can use a single resource to load translation files and avoid using exports / call.
Language key collisions can be handled in the order of loading (so the keys from last loaded file overwrite the existing ones).
Basically a global="true" scope option for .po files.

[Nico8340]

Personally, I'd rather implement this in Lua instead of directly in the project. It's easy to do there, and not every server actually needs it. Even if some do, the PO file based setup feels outdated now and probably wouldn't match what a lot of folks prefer.

[Nico8340]

Great job! This solution should be more efficient than Lua based options.

I'm wondering if it's feasible to add this functionality on client level (so translations could be shared across all resources). This way complex projects can use a single resource to load translation files and avoid using exports / call. Language key collisions can be handled in the order of loading (so the keys from last loaded file overwrite the existing ones). Basically a global="true" scope option for .po files.

The overhead of doing this in Lua is actually pretty minimal, especially for most use cases. You can load translations once in a resource and share them with others using call or even loadstring if needed.

[MohabCodeX]

The overhead of doing this in Lua is actually pretty minimal, especially for most use cases. You can load translations once in a resource and share them with others using call or even loadstring if needed.

What about exploring another solution instead of using Lua? I still believe there might be an option that satisfies both.

[FileEX]

Personally, I think this is a very good idea. It’s true that this can be achieved using regular Lua tables, but using .po files seems like a better, more appropriate, and professional solution, as it allows integration with automated platforms like Crowdin.

Additionally, it’s much simpler and easier than building an entire translation system from scratch. If someone prefers their own Lua-based solution, they can still stick with it—nobody is forced to use .po files. Using .po files is by no means outdated; the format is still widely used in the translation industry, and I see no reason why it couldn’t be used for translations on your server. It’s fully sufficient and straightforward.

As we can see from the reactions, this PR has been received positively.

The only thing I personally miss is some kind of automatic scaling option. Unfortunately, even MTA doesn’t currently have this feature. Specifically, I mean something like what’s used in GTA code—different languages have different characters; a short word in one language might be long in another, not to mention entire sentences. As a result, content in different languages is often cut off or not fully visible. For example, buttons may be too narrow to fit the same text in various languages (like in the admin panel). I’m not sure if this should be a separate PR or part of this one, or maybe it’s something that should be handled independently in Lua.