Add comprehensive language/internationalization documentation

Co-authored-by: nonprofittechy <7645641+nonprofittechy@users.noreply.github.com>

Author: Copilot

docs/components/AssemblyLine/magic_variables.md

@@ -199,6 +199,11 @@ your interviews directly or via a shared YAML file.
 
 ### Localization and translation variables
 
+These variables are used for basic address and language configuration.
+For the Assembly Line's advanced language switching system, see the
+[Assembly Line language system variables](#assembly-line-language-system-variables)
+section below and the [translation documentation](translation.md).
+
 * `AL_DEFAULT_COUNTRY`: [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166) 2
   letter code representing the default country of the interview user for address
   questions. E.g., `US` for United States of America, `UK` for United Kingdom of
@@ -390,6 +395,59 @@ choose to define this value on an organization-wide basis by placing it in a
 shared YAML file, such as the YAML that defines your theme or other branding
 elements.
 
+### Assembly Line language system variables
+
+These variables control the Assembly Line's built-in language switching system
+defined in `al_language.yml`. See the [translation documentation](translation.md)
+for complete usage examples.
+
+#### `enable_al_language`
+
+Controls whether the Assembly Line language system is active. Defaults to `True`.
+Set to `False` to disable the language switching functionality if you need to use
+a custom language system.
+
+```yaml
+code: |
+  enable_al_language = True
+```
+
+#### `al_user_default_language`
+
+The default language code (ISO 639-1 format) to use when a user hasn't selected
+a specific language. Defaults to `"en"` (English).
+
+```yaml
+code: |
+  al_user_default_language = "es"  # Default to Spanish
+```
+
+#### `al_interview_languages`
+
+A list of language codes (ISO 639-1 format) that your interview supports.
+When this list contains more than one language, the Assembly Line will
+automatically show a language selection dropdown in the navigation bar.
+
+```yaml
+code: |
+  al_interview_languages = ["en", "es", "fr"]  # English, Spanish, French
+```
+
+#### `al_user_language`
+
+The currently selected language for the user. This is typically set automatically
+through the language selection interface or URL parameters, but can be set directly
+if needed.
+
+#### `al_change_language` (event)
+
+An event triggered when the user clicks a language selection link. The event
+handler automatically updates `al_user_language` based on the `lang` action
+argument and calls Docassemble's `set_language()` function.
+
+This event is used internally by the language switching functions like
+`get_language_list_dropdown()` and `get_language_list()`.
+
 ## Run-time options
 
 These options are ones that you can sometimes configure when you author the

docs/components/AssemblyLine/translation.md

@@ -54,6 +54,9 @@ this.
 
 ## Variables used in translated interviews
 
+These variables control the Assembly Line's language system. For a complete list of
+all Assembly Line special variables, see [Special variables](magic_variables.md).
+
 * `enable_al_language`: defaults to True, turning it off can partially ensure the language system in AssemblyLine doesn't interfere with existing language systems. It should be relatively easy for authors to migrate to this new system though.
 * `al_user_default_language`: can be controlled by interview author, this determines the language when the user makes no selection of their own. Defaults to "en".
 * `al_interview_languages`: a list of language codes, presumably ISO-639-1 (Alpha-2), like ["en","es"] etc. The Assembly Line also contains a translation of several common language codes into the native-language version of the language (e.g., `es` is translated as `Español`).
@@ -172,6 +175,36 @@ If the URL already has a `?` in it, replace the `?` with an `&`.
 (this is a standard part of URL arguments).
 :::
 
+## The `al_change_language` event
+
+The Assembly Line language system uses a special event called `al_change_language`
+to handle language switching. This event is triggered automatically when a user
+clicks on a language selection link generated by functions like 
+`get_language_list_dropdown()` or `get_language_list()`.
+
+When the event is triggered, it:
+
+1. Reads the `lang` parameter from the action arguments
+2. Sets `al_user_language` to the selected language code
+3. Calls Docassemble's `set_language()` function to apply the language change
+
+You normally don't need to handle this event directly, as it's managed automatically
+by the language switching functions. However, if you want to add custom behavior
+when languages are switched, you can define additional logic after the language
+change:
+
+```yaml
+event: al_change_language
+code: |
+  # The built-in language switching happens first
+  if 'lang' in action_arguments():
+    al_user_language = action_argument('lang')
+    set_language(al_user_language)
+  
+  # Add your custom logic here
+  log(f"User switched to language: {al_user_language}")
+```
+
 ## A complete example
 
 ```yaml
@@ -249,4 +282,4 @@ If a language code is not listed in `languages.yml`, the Assembly Line functions
 
 You can read more about the stock language features in the official Docassemble [language features documentation](https://docassemble.org/docs/language.html).
 
-Also, see the documentation for the [AL language module](components/AssemblyLine/language.md)
+Also, see the documentation for the [AL language module](language.md) for complete API documentation of all language-related functions.