feature: Implement Glossaries for Firestore Translate Text Extension

[Gustolandia]

Overview

This pull request introduces support for glossaries in the Firestore Translate Text Extension. The feature allows for domain-specific translations, ensuring certain terms remain unaltered during translation or are translated as defined in a glossary. The implementation addresses the need for unmutable names, enhancing translation accuracy and flexibility.

Changes Made

1. Glossary Integration

• Added support for the Google Cloud Translation API's glossary feature.
• Updated the extension's parameters to include the following:
  • GLOSSARY_ID: Allows users to specify the ID of a glossary.
  • SOURCE_LANGUAGE_CODE: Required when using a glossary to define the source language.
• Ensured the feature respects glossary case sensitivity and added validation for glossary IDs.

2. Extension Configuration Updates

• Modified extension.yaml to:
  • Add GLOSSARY_ID, SOURCE_LANGUAGE_CODE, and GOOGLE_APPLICATION_CREDENTIALS parameters.
  • Mark GOOGLE_APPLICATION_CREDENTIALS as type: secret for enhanced security.
  • Include detailed descriptions and links to relevant documentation (e.g., how to create a glossary).
  • Clarified that glossaries require Translation Hub to be enabled.
  • Highlighted glossary case sensitivity.

3. Codebase Enhancements

• Updated translation logic to conditionally include glossary configurations in API requests.
• Ensured glossaries are only applied when specified and validated.
• Improved error handling for glossary-related operations.
  • Added logs and console output to track issues such as invalid glossary IDs or missing source language codes.
• Ensured minimal changes to existing functionality while integrating glossaries.

4. Testing

• Unit Tests:
  • Added new tests for glossary validation and integration:
    • Valid glossary IDs.
    • Error handling for invalid or non-existent glossaries.
    • Ensured translation requests include glossary configurations when specified.
  • Updated mocks to handle glossary-related scenarios, including errors and edge cases.
• Manual Testing:
  • Verified glossary functionality by manually testing with Firestore documents.
  • Tested various scenarios including valid glossaries, invalid glossaries, and translations without glossaries.

5. Documentation

• Updated README.md, PREINSTALL.md, and POSTINSTALL.md to:
  • Provide step-by-step instructions for enabling and using glossaries.
  • Include links to relevant resources (e.g., supported languages, glossary creation guide).
  • Clarify requirements such as source language specification and Translation Hub enablement.
  • Document the case-sensitive nature of glossaries.
  • Add troubleshooting tips for common glossary-related errors.

Manual Testing

Performed manual testing on a separate example app:

• Test Scenarios:
  • Translations with and without glossaries.
  • Glossaries with case-sensitive IDs.
  • Validating that translations respect glossary definitions.
• Results:
  • Confirmed that the source language is required when using glossaries.
  • Validated translations with various glossary setups.
  • Debugged and resolved issues related to glossary integration during testing.

Additional Notes

• The implementation ensures backward compatibility for users not leveraging glossaries.
• Glossary integration is limited to the Cloud Translation API and requires specific project setup.
• Enhanced logging and error handling improve debuggability and user feedback.

---

Thank you for reviewing this pull request. Please feel free to provide feedback or suggest further enhancements.

fixes: #2099

[cabljac]

we shouldn't guide them to mention service account keys (think this is leftover from original PR, should remove it)

[cabljac]

need to regenerate README