Add a translation guide for contributors #304
Conversation
|
@flpm i'm scrambling to get ready for scipy but my intent is to look at your PR's today / monday and get some things merged. THANK YOU for all of this work! i'm just a bit behind with all of the travel! I really suspect we can get some folks involved at SciPy with looking at these translations which will be amazing. it's the absolute perfect beginner-friendly sprint task for someone to work on that would have huge impact . |
There was a problem hiding this comment.
Filipe - this is awesome. i left a few comments
- let's open 2 new issues that people can work on related to our contributing guide. i can help with this once i understand any specifics related to the translation component!
- nox isn't running for me. if you could test this out and either let me now what I might be doing wrong OR it might just be a convert to string issue in the nox session, that would be great!
thank you again!!
| $ pip install .[dev] | ||
| ``` | ||
|
|
||
| TODO: This section needs more work or to be replaced with a reference to the CONTRIBUTING guide. |
There was a problem hiding this comment.
i'd like to create an issue for this (that will also be sprintable!). Our contributing guide should be updated to better explain how this all works! And we should have a section on contributing through the github GUI (which most new contributors do!)
can you help me understand what pieces you'd want here to the contributing guide that are specific to the localization process? Or what is missing? i'll then create a specific issue !
| You can do this by running the following command: | ||
|
|
||
| ```shell | ||
| $ nox -s update-translations |
There was a problem hiding this comment.
When i run this i get this error
nox > Session update-translations raised exception TypeError('sequence item 2: expected str instance, PosixPath found')
Traceback (most recent call last):
File "/Users/leahawasser/mambaforge/lib/python3.10/site-packages/nox/sessions.py", line 626, in execute
self.func(session)
File "/Users/leahawasser/mambaforge/lib/python3.10/site-packages/nox/_decorators.py", line 54, in __call__
return self.func(*args, **kwargs)
File "/Users/leahawasser/Documents/GitHub/pyos/python-package-guide/noxfile.py", line 156, in update_translations
session.run(SPHINX_BUILD, *TRANSLATION_TEMPLATE_PARAMETERS, SOURCE_DIR, TRANSLATION_TEMPLATE_DIR, *session.posargs)
File "/Users/leahawasser/mambaforge/lib/python3.10/site-packages/nox/sessions.py", line 287, in run
return self._run(*args, env=env, **kwargs)
File "/Users/leahawasser/mambaforge/lib/python3.10/site-packages/nox/sessions.py", line 360, in _run
return nox.command.run(args, env=env, paths=self.bin_paths, **kwargs)
File "/Users/leahawasser/mambaforge/lib/python3.10/site-packages/nox/command.py", line 87, in run
full_cmd = f"{cmd} {' '.join(args)}"
TypeError: sequence item 2: expected str instance, PosixPath found
nox > Session update-translations failed.
my suspicion is it relates to SOURCE_DIR being passed as a pathlib object rather than a string? @flpm does this work for you on your computer? or is it a mac specific thing on mine?
|
|
||
| To create a virtual environment and install the development dependencies for the guide, run the following commands: | ||
|
|
||
| ```shell |
There was a problem hiding this comment.
One more question - if we are using nox, what is the venv for? Could we remove this? nox will create an environment for us here.
we can use session.install and add any dependencies that we wish to the pyproject.toml dependencies section. (please forgive me if i'm missing a key element here!!)
|
|
||
| The review process for a translation contribution is similar to the review process for any other contribution to the guide. | ||
|
|
||
| TODO: This section needs more work, depending on the review workflow we decide to adopt. Other projects usually assign a coordinator/editor for each language, who is responsible for reviewing and merging translation contributions. |
There was a problem hiding this comment.
Ok great - let's turn this into an issue as well. We can see if can get someone in the community to help lead this!
|
ok this is all fantastic! I am going to merge it Filipe but also i want to open a new issue around our contributor guide. We might be able to pull a bit of the language from your guide here into our main contributor guide and cross link. |
This PR adds a translation guide to the Package Guide to help contributors get started contributing to the translation process.
The nox sessions described in the guide in this PR are defined in PR #298 (Add support for internationalization to the guide)
What was done
I wrote a first draft of a Translation Guide (TRANSLATING.md) similar to the CONTRIBUTING.md guide to help new contributors understand the Translation workflow and get started with the process.
It assumes the reader is on the beginner end of the technical spectrum (translation is a good opportunity for people new to open source) and does not necessarily know internationalization and localization, so it is a little on the verbose side.
This guide will also help the pyOpenSci community involved in the guide understand the changes proposed in PR #298, which is where the workflow described here is implemented.
In this initial draft I suggest some ideas that the pyOpenSci community should discuss and decide, they come from similar translation processes in other projects.
For example:
lang-esto help the coordinators/editors identify them? This could be automated in Github Actions.