Skip to content
Merged
Show file tree
Hide file tree
Changes from 9 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions Translation.md
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The command to build the translated version of the website also needs to be updated. Given we need to preprocess things in conf.py using the value of language we can't use -D anymore. Change:

# from sphinx-build -D language=<language-code> -b html DISCOVER/ DISCOVER/_build/html
# to
WEBSITE_LANGUAGE=<language-code> sphinx-build -b html DISCOVER/ DISCOVER/_build/html

when running sphinx-build first conf.py gets executed and then all the configuration values that have been defined from executing it are passed to the sphinx class that builds the website. -D option modifies the configuration values, but it does so after executing conf.py. This means that things like current_language_name = next((lang['name_local'] for lang in all_languages if lang['code'] == language), language) get executed with language set to the default instead of the variable passed through -D option

Original file line number Diff line number Diff line change
Expand Up @@ -44,4 +44,95 @@ DISCOVER/_build/html/index.html
```
and opening it in your browser.


> Note: Contributors working on multilingual support should ensure .po file updates are included in commits.


## Syncing with Transifex

We use Transifex as our translation service for the Cookbook, in order to collaborate on translations via Transifex, follow these steps:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would restrucuture the wording and sections around this. I think the vast majority of cases will/should not follow all these steps. I would instead focus on what each step does and when it should be executed. i.e. when a new page/chapter is added to the cookbook we need to add it to .tx/config, when we do any update to the content we need to regenerate source files via sphinx gettext and sphinx-intl then both open a PR with that and push to transifex (that includes the previous case when a new chapter is added but also updates to existing chapters), then at some other point (iiuc 100% manually) we need to pull translations from transifex so they make it into the published website


### Step 1: Install the Transifex CLI

Download the latest Go-based CLI from the [Transifex CLI releases](https://github.com/transifex/cli/releases).

Place the binary in a folder like ```C:\tx-cli``` and add it to your system’s PATH.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Link to the transifex website for the install instructions. Copying these over here makes them windows only and they could also become outdated more easily. I would instead link to the transifex instructions and then show how to verify the install was successful

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have made the changes, you can review it;)


Verify installation:
```sh
tx --version
```
Expected output:
```
TX CLient, version=1.6.x
```

### Step 2: Authenticate with Transifex

Create a ```.transifexrc``` file in your home directory ```(C:\Users\<yourname>\)``` with:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also link to the official documentation on authenticating


```python
[https://www.transifex.com]
rest_hostname = https://rest.api.transifex.com
token = 1/your_api_token_here
```
Get your token from [Transifex Account Settings](https://app.transifex.com/user/settings/api/).


### Step 3: Configure ```.tx/config```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think is will be needed ever again, covering adding more resources or deleting resources from it is probably fine. Again, I'd recommend using tx client for adding/deleting, and linking to the official docs even if we add the command in here.

This file lives in the root of the project and maps source files to Transifex resources.

```python
[main]
host = https://www.transifex.com
source_lang = en

[o:numfocus:p:DISCOVER-Cookbook:r:01_about]
source_file = locales/en/LC_MESSAGES/01_about.po
file_filter = locales/<lang>/LC_MESSAGES/01_about.po
type = PO
```

### Step 4: Push Source Files
To upload updated source files to Transifex:
```
tx push -s
```

To push translation files:
```
tx push -t
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't come up with any scenario where we'd want one of those but not the other. Can we use tx push -s -t all at once? Or explain when we'd want to use one without the other?


### Step 5: Pull Translations
To download all available translations:
```
tx pull -a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am adding translations on transifex right now and will review some but not others. Please make sure the command we add here pulls only reviewed translations but not translated but unreviewed content.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have added 4 translated+reviewed strings and 4 translated but not reviewed (the content of those strings says in English "This string is translated but not reviewed and should not be pulled from transifex") so you can easily check which way of pulling gets only reviewed content.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will check this

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tested this command in #368 and it downloads unreviewed translations. It needs to be:

Suggested change
tx pull -a
tx pull -a -m reviewed

```

### Optional: Add Multiple Resources

To register all .po files under locales/en/LC_MESSAGES:
```
Get-ChildItem -Path locales/en/LC_MESSAGES -Filter *.po | ForEach-Object {
$filename = $_.Name -replace '\.po$', ''
$sourcePath = "locales/en/LC_MESSAGES/$($filename).po"
$fileFilter = "locales/<lang>/LC_MESSAGES/$($filename).po"

& "tx" add `
--organization numfocus `
--project DISCOVER-Cookbook `
--resource $filename `
--file-filter $fileFilter `
--type PO `
"$sourcePath"
}
```

## Tips:

- Always use forward slashes (/) in paths for compatibility.
- Run ```tx status``` to check resource sync.
- Use ```tx config discovery``` to auto-detect new files.

### Need help? Reach out to the maintainers or open an issue!
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The target audience for this document will be the ones that will know the most about transifex and translations. I am not sure this is helpful in this situation

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is useful

207 changes: 207 additions & 0 deletions locales/en/LC_MESSAGES/01_about.po
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2023
# This file is distributed under the same license as the Project name not
# set package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2025.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Project name not set \n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2025-07-26 22:09+0530\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language: en\n"
"Language-Team: en <LL@li.org>\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.17.0\n"

#: ../../01_about.md:2
msgid "About"
msgstr ""

#: ../../01_about.md:4
msgid "Summary"
msgstr ""

#: ../../01_about.md:5
msgid ""
"This cookbook is intended as a resource for organizers of conferences and"
" events with a particular focus on the tech sector in the United States. "
"It focuses specifically on plans, decisions, and actions organizers can "
"take to produce and manage a more diverse and inclusive event. The "
"cookbook does not provide any specific advice about budgeting, "
"scheduling, A/V capabilities, how to structure tracks, etc."
msgstr ""

#: ../../01_about.md:7
msgid "About this Cookbook:"
msgstr ""

#: ../../01_about.md:9
msgid ""
"This cookbook is intended as a resource for **organizers of conferences "
"and events** — with a particular focus on the tech sector in the United "
"States — to **support and encourage diversity and inclusion** at those "
"events."
msgstr ""

#: ../../01_about.md:11
msgid ""
"It focuses specifically on plans, decisions, and actions organizers can "
"take to produce and manage a more diverse and inclusive event."
msgstr ""

#: ../../01_about.md:13
msgid ""
"_Funding to produce this cookbook was made possible by a generous grant "
"from the_ **Moore Foundation** _._"
msgstr ""

#: ../../01_about.md:15
msgid "**Further Reading:**"
msgstr ""

#: ../../01_about.md:16
msgid ""
"[DISCOVER Cookbook Checklist](/13_inclusive-checklist.md) — A practical "
"checklist for conference organizers to implement inclusive measures "
"effectively."
msgstr ""

#: ../../01_about.md:18
msgid "What this Cookbook is not:"
msgstr ""

#: ../../01_about.md:20
msgid ""
"This cookbook is **not** intended to provide **general instructions** on "
"how to run a successful conference or event. We do not provide any "
"specific advice about budgeting, scheduling, A/V capabilities, how to "
"structure tracks, etc."
msgstr ""

#: ../../01_about.md:22
msgid ""
"Some &quot;basic&quot; best practice is understood to be a prerequisite "
"for many of our recommendations. For example, live-captioning support for"
" the hearing-impaired is not possible without reliable internet and good "
"A/V setup. In general, we have avoided explicitly calling out these "
"implied dependencies in order to maintain focus and keep the cookbook to "
"a more manageable length."
msgstr ""

#: ../../01_about.md:24
msgid ""
"This cookbook also does not offer reasons or rationale for **why "
"inclusion and diversity are important**. The cookbook presumes the "
"organizing committee is already interested in improving diversity and "
"inclusion at their conference or event. Hence the suggestions herein are "
"focused on the &quot;how&quot; rather than the &quot;why&quot;."
msgstr ""

#: ../../01_about.md:27
msgid "Acknowledgements:"
msgstr ""

#: ../../01_about.md:29
msgid ""
"We sincerely appreciate the efforts and input of the many individuals who"
" contributed to the creation of this cookbook. We also thank the numerous"
" individuals and organizations whose work we have drawn from in order to "
"compile this cookbook. Resources we consulted are collected at the end of"
" each section under the heading &quot;Further Reading&quot;."
msgstr ""

#: ../../01_about.md:31
msgid "In particular, we thank:"
msgstr ""

#: ../../01_about.md:33
msgid ""
"The NumFOCUS DISC Committee members who compiled the initial skeleton of "
"this cookbook: Jennifer Klay, Reshama Shaikh, and Gina Helfrich. And "
"those who set up this page: Mwai Karimi, Bojan Božić and Leonie Mueck"
msgstr ""

#: ../../01_about.md:35
msgid ""
"Participants in the 2017 DISC Unconference who expanded and elaborated "
"upon the initial skeleton: Kasia Rachuta, Ashley Otero, Dave Clements, "
"Sarah Supp, Raniere Silva, and Tania Allard."
msgstr ""

#: ../../01_about.md:38
msgid "Other Considerations"
msgstr ""

#: ../../01_about.md:40
msgid "**Further reading:**"
msgstr ""

#: ../../01_about.md:42
msgid ""
"[Scent and smoking policy](https://adacamp.org/adacamp-"
"toolkit/policies/#scent)"
msgstr ""

#: ../../01_about.md:43
msgid ""
"[Conference booklet "
"template](http://geekfeminism.wikia.com/wiki/Conference_booklet_template)"
msgstr ""

#: ../../01_about.md:46
msgid "Special Considerations Depending on Geographic Context"
msgstr ""

#: ../../01_about.md:48
msgid ""
"Most of the material contained herein is written from the U.S. "
"perspective (e.g. Americans with Disabilities Act (ADA) protections)."
msgstr ""

#: ../../01_about.md:49
msgid ""
"Something to be aware of: some U.S. states may have discriminatory laws "
"in place which could affect whether you should choose to host an event or"
" conference there."
msgstr ""

#: ../../01_about.md:50
msgid ""
"We welcome input on considerations for events and conferences in other "
"countries."
msgstr ""

#: ../../01_about.md:51
msgid ""
"Additional considerations may need to be made for very remote event "
"locations with no public transit, e.g. for folks who are mobility "
"impaired."
msgstr ""

#: ../../01_about.md:55
msgid "REQUEST FOR INPUT"
msgstr ""

#: ../../01_about.md:57
msgid ""
"NumFOCUS invites the community to make suggestions for improvements to "
"the DISCOVER Cookbook via pull request (PR). PRs will be evaluated by the"
" NumFOCUS DISC Committee and/or its volunteers. PRs should be written so "
"as to conform to the [NumFOCUS Contributor Code of "
"Conduct](https://www.numfocus.org/about/code-of-conduct/)."
msgstr ""

#: ../../01_about.md:59
msgid ""
"For a full statement of the NumFOCUS DISC Program mission and the "
"NumFOCUS position on diversity and inclusion, please see [Diversity and "
"Inclusion](https://www.numfocus.org/programs/diversity-and-inclusion/)."
msgstr ""

Loading