-
Notifications
You must be signed in to change notification settings - Fork 57
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into sysadmin-note-http2
- Loading branch information
Showing
283 changed files
with
1,477 additions
and
399 deletions.
There are no files selected for viewing
This file contains 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
This file contains 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
This file contains 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
139 changes: 139 additions & 0 deletions
139
_docs/developer/development_instructions/localization.md
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,139 @@ | ||
| --- | ||
| title: Localization / Language Support | ||
| category: Developer > Development Instructions | ||
| redirect_from: | ||
| - /developer/migrations | ||
| --- | ||
|
|
||
|
|
||
| The goals of localization or internationalization include the | ||
| translation of the website into multiple languages, to increase the | ||
| accessibility of Submitty to users in all locales or regions. | ||
|
|
||
| To contribute to Submitty's localization and translation efforts, | ||
| follow these steps to update Twig templated files and provide | ||
| translations for various text elements on the website. | ||
|
|
||
| --- | ||
|
|
||
| ## Server Language Specification | ||
|
|
||
| By default, all Submitty pages will display in English based on the | ||
| `en_US` locale. To modify the server default setting, the system | ||
| administrator should edit the | ||
| `/usr/local/submitty/config/submitty.json` file and add this line, e.g.: | ||
|
|
||
| ``` | ||
| "default_locale": "fr_FR", | ||
| ``` | ||
|
|
||
| to specify an alternate locale. | ||
| See also [Php Locale class](https://www.php.net/manual/en/class.locale.php). | ||
|
|
||
| --- | ||
|
|
||
| ## Individual Language Specification | ||
|
|
||
| Each individual user can specify their own preferred locale if they do | ||
| not wish to use the server default. Navigate to "My Profile" and | ||
| choose the desired language and region settings. | ||
|
|
||
|  | ||
|
|
||
| The dropdown menu will include all locales for which any translation | ||
| is available in the | ||
| [Localization](https://github.com/Submitty/Localization/tree/main/lang) | ||
| repository. Where translation to the requested language is | ||
| incomplete, the `en_US` locale will be used. | ||
|
|
||
| --- | ||
|
|
||
| ## Prepare a Website Page for Translation | ||
|
|
||
| Submitty uses the Twig template engine to manage html source code with | ||
| Php. Checkout the [Submitty source | ||
| code](https://github.com/Submitty/Submitty) and locate the specific | ||
| `.twig` template file(s) associated with the webpage that you would | ||
| like to update. | ||
|
|
||
|
|
||
| Identify an untranslated English plain text string in the Twig source | ||
| code, for example: | ||
|
|
||
| ``` | ||
| <p>Text in the page I will translate</p> | ||
| ``` | ||
|
|
||
|
|
||
| And replace that text string with the following syntax: | ||
|
|
||
| ``` | ||
| <p> { { localize("Page_Description.Text_To_Translate", "Text in the page I will translate") } } </p> | ||
| ``` | ||
|
|
||
| The `localize` function requires two arguments: | ||
|
|
||
| * The first argument is the hierarchical tag or label, separated by | ||
| one or more dots. The hierarchy should begin with the name of the | ||
| page, and intuitively name and organize/group all phrases that | ||
| appear on that page. The first part represents the role or purpose | ||
| of the page, while the second (and later) parts describes the text | ||
| you're translating. Use underscores to replace spaces in this part. | ||
| Avoid using apostrophes, quotes, accents, and other special | ||
| characters. | ||
|
|
||
| * The second argument is the original English text that will be | ||
| displayed on the website if a translation in the user's language is | ||
| not available. | ||
|
|
||
|
|
||
| Make a [pull request](/developer/getting_started/make_a_pull_request) | ||
| with your proposed changes. | ||
|
|
||
| --- | ||
|
|
||
| ## Updating the en_US.json Phrase File | ||
|
|
||
| When Twig files are edited to prepare or update one or more pages for | ||
| translation, these pages will be reviewed and merged. | ||
|
|
||
| When a new release/version of the Submitty source code is published | ||
| with changes to one or more `.twig` files, **[TODO]** the | ||
| [`en_US.json` file in the Localization repository](https://github.com/Submitty/Localization/blob/main/lang/en_US.json) | ||
| will be automatically updated. | ||
|
|
||
| --- | ||
|
|
||
| ## Adding Translations to the Localization Repository | ||
|
|
||
| Once the pull request is merged and a new version of Submitty is | ||
| released, checkout the [Localization](https://github.com/Submitty/Localization/tree/main/lang) | ||
| repository and navigate to the `Localization/lang` directory. | ||
|
|
||
| If a JSON file for the language you're translating to isn't available, | ||
| create one. The file name format is as follows: | ||
| ``` | ||
| <language_code>_<country_code>.json | ||
| ``` | ||
|
|
||
| Copy the content of the en_US.json file and paste it into the newly | ||
| created or existing JSON file. | ||
|
|
||
| Edit the JSON file by translating the "Text in the page I will | ||
| translate" text within the "Page_Description" section. The JSON file | ||
| format should resemble the following: | ||
|
|
||
| ``` | ||
| { | ||
| "Page_Description": { | ||
| "Text_To_Translate": "Translated text for the page" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| You should test your translation by following the | ||
| [Development Instructions](/developer/development_instructions/index#incremental-development-updates). | ||
|
|
||
| When you are finished, submit a pull request to the Localization | ||
| repository with your new and/or modified JSON files. | ||
|
|
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| --- | ||
| title: Sample Courses Data | ||
| category: Developer > Development Instructions | ||
| redirect_from: | ||
| - /developer/development_instructions/sample_data | ||
| --- | ||
|
|
||
| As a developer, there are 5 sample courses: | ||
| - **BLANK** | ||
| - Empty course. | ||
| - **DEVELOPMENT** | ||
| - All files from `/more_autograding_examples/`, which mostly tests autograding. | ||
| - Most new features that need gradeables to test them will be put here. | ||
| - **SAMPLE** | ||
| - A simultation of a "live" course mid-semester with lots of students and lots of submissions. Tests features such as ta grading, due dates, categories, etc. | ||
| - For manual & automated website testing. | ||
| - **TUTORIAL** | ||
| - All tutorial gradeables are in sequence, emphasizing one new feature as they grow in complexity. | ||
| - **PLAGIARISM** | ||
| - Used to test Lichen plagiarism detection. | ||
| - This is not available by default. You must clone the [Lichen Test Data](https://github.com/Submitty/LichenTestData) repository locally to see this. | ||
|
|
||
| --- | ||
|
|
||
| ## Predefined Data | ||
|
|
||
| Predefined data is set using files in `/.setup/data/` and the script `/.setup/bin/setup_sample_courses.py`. | ||
|
|
||
| | Data | Location | | ||
| |------|----------| | ||
| | Course Gradeables | `/.setup/data/courses` | | ||
| | Forum Threads | `/.setup/data/forum` | | ||
| | Polls | `/.setup/data/polls` | | ||
| | Office Hours Queue | `/.setup/data/queue` | | ||
| | Team Assignment | `/.setup/data/teams` | | ||
| | Predefined Users | `/.setup/data/users` | | ||
|
|
||
| --- | ||
|
|
||
| ## Sample Courses Student Data | ||
|
|
||
| Sample Courses Student Data is set using `.yml` files and the script `/.setup/bin/setup_sample_courses.py`. | ||
|
|
||
| #### Predefined Users | ||
|
|
||
| `setup_sample_courses.py` parses the yaml files in `.setup/data/users/`. If you want to know more about how to write the user yaml files, read `.setup/data/users.yml`, which explains all the options. | ||
|
|
||
| #### Random Users | ||
|
|
||
| `setup_sample_courses.py` also generates random users. Randomly generated users generate random family and given names, user ids based on the names chosen, random anonymous user ids, numeric ids, and pronouns. For more information, read the `generate_random_users` function in `setup_sample_courses.py`. | ||
|
|
||
| Randomly generated students are the same in every build, unless you make changes to `setup_sample_courses.py` or related files. This is because the random seed is set to a specific value. This decision was to keep test cases consistent. However, if you make changes that utilize randomness, it may change the randomly generated students, thus making the test cases obsolete. | ||
|
|
||
| If you make changes that use/alter random number generation, you may need to | ||
| edit the following files: | ||
| - Peer Review: | ||
| - `.setup/data/random/students.txt` | ||
| - `.setup/data/random/graders.txt` | ||
| - Office Hours Queue: | ||
| - `.setup/data/queue/queue_data.json` | ||
| - Discussion Forum: | ||
| - `.setup/data/forum/threads.txt` | ||
| - `.setup/data/forum/posts.txt` | ||
| - Teams: | ||
| - `.setup/data/teams/sample_open_team_homework_teams.csv` | ||
|
|
||
| These files are manually written for a given set of users (the set is predetermined due to | ||
| the random's seed staying the same). If you make any changes that affects the contents of the | ||
| set these files will be outdated and result in failure of recreate_sample_courses. | ||
|
|
||
| You may also need to edit test cases in Cypress, Selenium, etc. | ||
|
|
||
| --- | ||
|
|
||
| See also: [Re-Creating All Sample Course Data](/developer/development_instructions/index#re-creating-all-sample-course-data) | ||
|
|
Oops, something went wrong.