You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
In this section I added an index.md file as a placeholder to introduce documentation of language packs as extensions and two articles based on my own experience. They may be too personal for the Manual! I would not be offended if others considered them inappropriate for the Programmers Documentation.
PR Type
Documentation
Description
Added comprehensive language pack documentation section
Included Scottish Gaelic extension example with complete structure
Provided OpenAI translation automation script and methodology
Documented language pack creation, installation, and build processes
Changes diagram
flowchart LR
A["Language Pack Documentation"] --> B["Extension Structure"]
A --> C["Translation Methods"]
B --> D["Package Files"]
B --> E["Client Configurations"]
C --> F["OpenAI Translation"]
C --> G["Build Process"]
Loading
Changes walkthrough 📝
Relevant files
Documentation
index.md
Language pack documentation overview
docs/building-extensions/languages/index.md
Created language pack documentation index page
Explained language pack structure and components
Listed different types of language documentation needs
Added references to existing translation resources
Here are some key observations to aid the review process:
⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 Security concerns
API key exposure: The translation script contains a placeholder for an OpenAI API key that could accidentally be committed with real credentials. Additionally, the script disables SSL verification (CURLOPT_SSL_VERIFYHOST and CURLOPT_SSL_VERIFYPEER set to false) which creates a security vulnerability by allowing man-in-the-middle attacks during API communications.
The script contains hardcoded API key placeholder and uses curl with SSL verification disabled, which could lead to security vulnerabilities if used as-is in production environments.
private static $open_ai_key = 'your_api_key_goes_here';
/*** URL of current version of the API endpoint.
*/
private static $open_ai_url = 'https://api.openai.com/v1';
/*** Process one of the client ini folders
**@param string $folder The name of the folder: api, admin or site
**@return void
*/
public function go($folder) {
switch ($folder) { case 'api': $source = "api/language/en-GB/"; $sink = "/Users/ceford/git/cefjdemos-pkg-gd-gb/gd-GB/api_gd-GB/"; break; case 'admin': $source = "administrator/language/en-GB/"; $sink = "/Users/ceford/git/cefjdemos-pkg-gd-gb/gd-GB/admin_gd-GB"; break; case 'site': $source = "language/en-GB/"; $sink = "/Users/ceford/git/cefjdemos-pkg-gd-gb/gd-GB/site_gd-GB/"; break; default: die("unkown folder: {$folder}\n");}// Read in the list of source files.$files = file_get_contents(__DIR__ . "/{$folder}.txt");$lines = explode(PHP_EOL, $files);$count = 0;$pattern = '/(.*)"(.*)"/';foreach ($lines as $line) { if (empty(trim($line))) { continue; } // If the translation has been done, skip this file. if (is_file($sink . $line)) { continue; } // Create an empty file. file_put_contents($sink . $line, ""); // Read in the English ini file. $inifile = file_get_contents($this->base . $source . $line); echo "Processing {$source}{$line}\n"; $inilines = explode(PHP_EOL, $inifile); $inicount = 0; $batch = []; foreach ($inilines as $iniline) { $test = preg_match($pattern, $iniline, $matches); if (!empty($test)) { // The key is in $matches[1] and the value in $matches[2] $keys[$inicount] = $matches[1]; // Add the whole line to the batch $batch[] = $matches[0]; $inicount += 1; // If the batch is a multiple of 25 send it for translation. if ($inicount % 25 === 0) { file_put_contents($sink . $line, $this->translateme($batch), FILE_APPEND); $batch = []; } } else { // Output any pending batch translations. if (!empty($batch)) { file_put_contents($sink . $line, $this->translateme($batch), FILE_APPEND); } // Output the line unchanged file_put_contents($sink . $line, "{$iniline}\n", FILE_APPEND); $batch = []; } } // Translate any lines still in the batch; if (!empty($batch)) { file_put_contents($sink . $line, $this->translateme($batch), FILE_APPEND); } $count += 1;}echo "Total = {$count}\n\n";
}
/*** Prepare a batch of lines for translation
**@param array $batch The array of lines so far.
*/
protected function translateme($batch) {
$text = implode("\n", $batch);
// submit a batch of lines to openai.com for translation.$translation = $this->getTranslation('Scottish Gaelic', $text);return "{$translation}\n";
}
/*** Compose the message to be sent to openai.com
**@param string $language_name The name of the destination language in English
*@param string $paragraphBuffer The text to be translated.
**@return string The translated text or the original text with comments.
*/
protected function getTranslation($language_name, $paragraphBuffer) {
$instruction = "Please translate the following ini file text from English to {$language_name}";
if ($language_name == 'German') {
$instruction .= ' Please use the word Beiträge rather than Artikel. ';
}
$messages = [ [ "role" => "system", "content" => "You are a translator who translates text from English to {$language_name}. " . "Provide only the translated text, without any comments or explanations. " . "The text is in ini file format with a key followed by the value to be translated in double quotes" . "The translated value must be on one line." ], [ 'role' => 'user', 'content' => $instruction . ": \n" . $paragraphBuffer, ],];$return = $this->chat($messages);if (empty($return['choices'])) { // Find out what is going on! //var_dump($return, $messages); echo "Untranslated text: " . substr($paragraphBuffer, 0, 64) . "\n"; return "<!-- untranslated -->\n{$paragraphBuffer}\n<!-- enduntranslated -->\n";} else { return $return['choices'][0]['message']['content'];}
}
/*** Set the openai parameters and create a message: https://platform.openai.com/docs/api-reference/chat/create**@param array $messages (each item must have "role" and "content" elements, this is the whole conversation)
*@param int $maxTokens maximum tokens for the response in ChatGPT (1000 is the limit for gpt-3.5-turbo)
*@param string $model valid options are "gpt-3.5-turbo", "gpt-4", and in the future probably "gpt-5"
*@param int $responseVariants how many response to come up with (normally we just want one)
*@param float $frequencyPenalty between -2.0 and 2.0, penalize new tokens based on their existing frequency in the answer
*@param int $presencePenalty between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the conversation so far, increasing the AI's chances to write on new topics.
*@param int $temperature default is 1, between 0 and 2, higher value makes the model more random in its discussion (going on tangents).
*@param string $user if you have distinct app users, you can send a user ID here, and OpenAI will look to prevent common abuses or attacks
*/
protected function chat(
$messages = [],
$maxTokens=2000,
$model='gpt-4o',
$responseVariants=1,
$frequencyPenalty=0,
$presencePenalty=0,
$temperature=1,
$user='') {
//create message to post$message = new stdClass();$message -> messages = $messages;$message -> model = $model;$message -> n = $responseVariants;$message -> frequency_penalty = $frequencyPenalty;$message -> presence_penalty = $presencePenalty;$message -> temperature = $temperature;if($user) { $message -> user = $user;}$result = self::_sendMessage('/chat/completions', data: json_encode($message));return $result;
}
/*** Send the request message to openai.
**@param string $endpoint Endpoint obtained from the openai url
*@param string $data The json encoded data to be sent.
*@param string $method Deafults to post.
**@return object The response to the request.
*/
private static function _sendMessage($endpoint, $data = '', $method = 'post') {
$apiEndpoint = self::$open_ai_url.$endpoint;
$curl = curl_init();if($method == 'post') { $params = array( CURLOPT_URL => $apiEndpoint, CURLOPT_SSL_VERIFYHOST => false, CURLOPT_SSL_VERIFYPEER => false,
The build configuration and script contain hardcoded absolute file paths that are specific to the author's development environment, making the examples less portable and potentially confusing for other developers.
<authorUrl>https://github.com/ceford/cefjdemos-pkg-gd-gb</authorUrl><copyright>(C) 2025 Clifford E Ford. All rights reserved.</copyright><license>GNU General Public License version 2 or later; see LICENSE.txt</license><url>https://github.com/ceford/cefjdemos-pkg-gd-gb</url><packager>Clifford E Ford</packager><packagerurl>https://github.com/ceford/cefjdemos-pkg-gd-gb</packagerurl><description><![CDATA[Scottish Gaelic translation created by openai.com]]></description><blockChildUninstall>true</blockChildUninstall><scriptfile>script.php</scriptfile><files> <file type="language" client="site" id="gd-GB">site_gd-GB.zip</file> <file type="language" client="administrator" id="gd-GB">admin_gd-GB.zip</file> <file type="language" client="api" id="gd-GB">api_gd-GB.zip</file></files><updateservers> <server type="extension" priority="2" name="Scottish Gaelic Update Site">https://github.com/ceford/cefjdemos-pkg-gd-gb/raw/main/pkg_gd-GB.zip</server></updateservers>
</extension>
The extension version is usually the same as the Joomla version for which it was created. An optional extra parameter may be used for updates, for example 5.3.1.1. When creating a third party extension take care not to copy any Official Joomla! elements. The JED Checker will flag some as invalid.
The script.php file
This file is used to perform additional changes during extension install, update or uninstall. It is stored in the administrator/manifests/packages/gd-GB folder.
The API key is hardcoded as a placeholder string which will cause authentication failures. Consider using environment variables or configuration files to securely store the API key instead of hardcoding it in the source code.
-private static $open_ai_key = 'your_api_key_goes_here';+private static $open_ai_key;+public function __construct() {+ self::$open_ai_key = $_ENV['OPENAI_API_KEY'] ?? getenv('OPENAI_API_KEY');+ if (empty(self::$open_ai_key)) {+ throw new Exception('OpenAI API key not found in environment variables');+ }+}+
Apply / Chat
Suggestion importance[1-10]: 7
__
Why: This is a valid security best practice, but the code is an example script in documentation with a clear placeholder your_api_key_goes_here, which mitigates the immediate risk.
Medium
General
Improve error handling and logging
The error handling silently returns untranslated content without proper logging or retry mechanisms. This could lead to incomplete translations going unnoticed. Add proper error logging and consider implementing retry logic for failed API calls.
[To ensure code accuracy, apply this suggestion manually]
Suggestion importance[1-10]: 6
__
Why: The suggestion to add formal logging with error_log is a good practice, but the existing code already reports errors to the console, so the improvement to robustness is moderate for this example script.
Low
Increase timeout for API reliability
The 90-second timeout may be insufficient for large translation batches, potentially causing incomplete translations. Consider implementing exponential backoff or increasing the timeout for better reliability with API rate limits.
Why: Increasing the timeout and adding a connection timeout can improve the script's reliability, but the current value of 90 seconds is already quite generous for the described batch sizes.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User description
In this section I added an index.md file as a placeholder to introduce documentation of language packs as extensions and two articles based on my own experience. They may be too personal for the Manual! I would not be offended if others considered them inappropriate for the Programmers Documentation.
PR Type
Documentation
Description
Added comprehensive language pack documentation section
Included Scottish Gaelic extension example with complete structure
Provided OpenAI translation automation script and methodology
Documented language pack creation, installation, and build processes
Changes diagram
Changes walkthrough 📝
index.md
Language pack documentation overviewdocs/building-extensions/languages/index.md
language-extension-example.md
Complete language extension implementation exampledocs/building-extensions/languages/language-extension-example.md
translate-openai.md
OpenAI automated translation implementation guidedocs/building-extensions/languages/translate-openai.md