----------------------------------------------------------------------------------------------------------------------------------------------------------------
COPYRIGHT INFORMATION ...
HRConvert2, Copyright on 5/5/2023 by Justin Grimes, www.github.com/zelon88

LICENSE INFORMATION ...
This project is protected by the GNU GPLv3 Open-Source license.
https://www.gnu.org/licenses/gpl-3.0.html

APPLICATION INFORMATION ...
This application is designed to provide a web-interface for converting file formats on a server for users of any web browser without authentication. 

FILE INFORMATION ...
v3.2.9.
This plain text file describes the process for creating, formatting, and installing additional language packs into HRConvert2.

HARDWARE REQUIREMENTS ... 
This application requires at least a Raspberry Pi Model B+ or greater. 
This application will run on just about any x86 or x64 computer.

DEPENDENCY REQUIREMENTS ... 
This application requires Debian Linux (w/3rd Party audio license), Apache 2.4, PHP 8+, LibreOffice, Unoconv, ClamAV, Tesseract, Rar, Unrar, Unzip, 7zipper, 
Ffmpeg, PdfToText, Dia, PopplerUtils, MeshLab, Mkisofs & ImageMagick.

ADDITIONAL INFORMATION
HRConvert2 has one default language set in config.php and multiple languages that can be selected by the user at runtime.
The default language used by HRConvrt2 can be selected by adjusting the --Default Language-- section of config.php.
Administrators can prevent user language selection by adjusting the --Allow User Selectable Language-- section of config.php.
If --Allow User Selectable Language-- is set to TRUE in config.php, users can adjust language output using a 'language' GET request.
To send a GET request, append the following string to the end of the HRConvert2 URL (without quotes):  '?language=<LANGUAGE_CODE>'
Substitute <LANGUAGE_CODE> in the string above for the 2 digit ISO 639-1 language code for the desired language.
If a user submits an unsupported language the default will be used instead.
It a supported language is missing required files a fatal error will occur.

<3 Open-Source
----------------------------------------------------------------------------------------------------------------------------------------------------------------



----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Language Packs--
 
HRConvert2 is designed to make localization into a new language by creating 'language packs' easy.
This document will teach administrator and developers how languages are handled and structured.
In this document when we refer to a GUI, we refer to a set of files required to render HRConvert2.
In this document when we refer to a language pack, we refer to the files required to localize a GUI into a specific language.

An HRConvert2 Language Pack is made up of 2 components. Each component serves a specific function. The 2 components of a Language Pack are;

  1. languageStrings.php
  2. index.html

These components are stored in a folder named after the ISO 639-1 language code for the language.
The ISO-639-1 named folder is then placed inside the 'UI\<GUI>\Languages' subdirectory of the installation location.
The supported ISO 639-1 language code must also be added to the --Supported Languages-- section of config.php or it will be ignored.
If --Allow User Selectable Language-- is enabled, users will be able to select this language pack by sendiing a GET request.
Users should not access the GUI directly. All requests should be directed to convertCore.php which will construct the GUI on-demand.

During operation, HRConvert2 initializes the language using the following process;

  1. Initialize the language to english.
  2. Build an array of languages that are included with HRConvert2.
  3. Check if the $SupportedLanguages variable from config.php is set properly.
    3a. If not, use the included array of default languages instead.
  4. If a language was specified via GET input, sanitize it.
  5. Check if the $DefaultLanguage variable from config.php is set & supported.
    5a. If not, use english instead.
  6. Check if the $AllowUserSelectableLanguage variable from config.php is set.
    6a. If not, use $DefaultLanguage instead.
  7. Check if a language was specified via GET input.
    7a. If not, use $DefaultLanguage instead.
  8. Check if the specified language is supported.
    8a. If not, use $DefaultLanguage instead.
  9. If all checks have passed and the specified language is supported, set the language to use to the one specified via GET request.
  10. Reset the language GET variable to the currently specified language so future requests will continue using the same language.
  11. Define all required language related files & folders.
  12. Check for the existence of all required language related files & folders.
    12a. If not, terminate the application.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--Administration Tips--

Language Packs are contained within GUIs. GUIs typically contain multiple language packs.
Errors will occur if an installed GUI does not support every language listed in the --Supported Languages-- section of the config.php file.
Errors will occur if an installed GUI does not support the following colors: Red, Green, Blue, Grey.
Server administrators can; 
  Enable or disable language packs by modifying the --Supported Languages-- section of the config.php file.
  Add or remove language packs to a GUI by creating a folder in the 'Languages' subdirectory of each enabled GUI folder.
  Allow or prevent language selection via GET request by modifying the --Allow User Selectable Languages-- section of the config.php file.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--Development Tips--

The modular design of HRConvert2 is designed to make modifications easily translatable to other languages.
If you are maintaining a branch of HRConvert2 and are focusing on a single language pack you can build your logic directly into the GUI pages themselves.
Any language pack files that are not needed can be left blank after the opening PHP tag.
To translate HRConvert2 into a new language, copy an existing language pack and translate the 'Languages\<LANGUAGE_CODE>\languageStrings.php' file into the desired language.
To install a new language pack, place a folder named after a 2 digit ISO 639-1 language code into the 'Languages' subdirectory of the installation location.
To enable or disable a language pack, update the --Supported Languages-- section of the config.php file.
GUIs can utilize the icons and scripts in the default Resources directory or include their own.
If any non-stock directories are added to HRConvert2, a copy of index.html must be pasted into the directory.
Do not create any files named index.html. This filename is reserved by the application for document root protection mechanisms.
Upper Case variables are Global in scope. Lower case variables are severely limited in scope. 
Limited scope variables should be manually nulled & unset after they are no longer required.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--Maintenance Tips--

The 'Languages\<LANGUAGE_CODE>\languageStrings.php' file should be used to contain all localization specific code.
By placing localization specific code into 'Languages\<LANGUAGE_CODE>\languageStrings.php', GUI updates can be easily applied from one language pack to another.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About languageStrings.php--

This file contains the major language-specific text elements & logic.
This file is loaded whenever a GUI is displayed.
This file exists to make the other GUI files more universal.
All translated text or text elements should be placed in this file & called by variable reference.
Using this file to contain localized text elements improves the maintainability of multiple language packs.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About index.html--

This file serves to act as reliable and predictable document root protection for the server.
If users are allowed to view the document root of the server they could navigate manually to other users hosted scratch space.
This would allow users to see some temporary files of other users while they were in the process of working on them.
This file simply redirects the user to the main HRConvert2 landing page with a message asking them to wait.
The visual effect of the loading text is that a malicious actor knows they have hit some protection mechanism.
If you want to modify the global index.html file, modify the one in the installation location and then copy & paste to all other subdirectories.
HRConvert2 will automatically create new index.html files in folders it creates using the one from the installation location as a template.
This file must be manually copied & pasted into any folders that are manually created by administrators or developers of HRConvert2.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About 'Languages' Folder--

This folder must exist in each language pack.
This folder contains the major language-specific files.
Each subdirectory of this folder represents a different language pack.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Open Source--

This application is open-source under the terms of the GPLv3 license, meaning anybody can obtain a copy and put it to use for personal or business use.
If you modify this application and use it to make money or offer it to your users as a product, you MUST make the source code with your changes available.
The ideal way to do this would be to fork the official zelon88/HRConvert2 repository on Github and make changes there.
Alternatively you can submit a pull request and have your changes added to the official repository (with credit due to you, of course).
By reciprocating changes & improvements with one another we can all enjoy the best, most capable and bug free version HRConvert2.
If you modify this codebase please consider making your changes public so everyone can benefit from them. 
----------------------------------------------------------------------------------------------------------------------------------------------------------------